Skip to content

feat(platform): add webhooks module to the server entrypoint - #319

Open
ozsay wants to merge 3 commits into
feat/platform-server-entrypointfrom
feat/platform-server-webhooks
Open

ozsay wants to merge 3 commits into
feat/platform-server-entrypointfrom
feat/platform-server-webhooks

Conversation

@ozsay

@ozsay ozsay commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #316 (base is that branch; retarget to main once it merges).

Summary

  • platform.webhooks.verifyEvent(rawBody, headers, { publicKeys, toleranceSeconds? }) verifies Standard Webhooks v1a (Ed25519) signatures with WebCrypto only, so it runs on Node 20+, Deno, Bun and edge runtimes. Returns a typed WebhookEvent; nothing is parsed before the signature passes. Makes no network calls.
  • platform.webhooks.createHandler({ publicKeys, on, onEvent, onSuccess, onError, toleranceSeconds? }) returns a fetch-style (request: Request) => Promise<Response>:
    • reads the raw body, verifies, and answers the webhook.test.v1 activation challenge itself (callbacks never see the probe);
    • runs onEvent, then the per-type handler from on (event narrowed per key), then onSuccess;
    • responds 204 on success (including types without a handler), 400 on a verification failure, 500 on misconfigured keys or a throwing callback so Base44 retries;
    • onSuccess / onError may return a Response to override the default.
  • Errors: WebhookVerificationError (400) vs WebhookConfigurationError (missing/malformed keys, 500).
  • Configuration: createBase44PlatformServer takes only the shared serverUrl / apiKey; each module handles its own settings. The webhooks module takes publicKeys on every call that verifies (verifyEvent, createHandler); there is no module-level init/config. No env reads, no key fetching.
  • Types: per-event data interfaces and WebhookEventMap are generated from the schemas published at https://base44.com/webhooks/schemas by npm run generate:webhooks (event list in scripts/webhook-event-types.json; --from <dir> for a local apper checkout).
  • Adds engines.node >=20, README section, two examples (verifyEvent + switch, and createHandler), and json-schema-to-typescript as a devDependency.

Test plan

  • npm test -w @base44/platform (type tests incl. per-handler narrowing, 63 unit tests incl. tamper/relabel/stale/rotation/config and handler status/callback ordering, typedoc, packed-package runtime and declaration checks)
  • npx eslint packages/platform

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

🚀 Package Preview Available!


Install this PR's preview build with npm:

npm i @base44-preview/sdk@0.8.53-pr.319.3e74a61

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/sdk:

npm i "@base44/sdk@npm:@base44-preview/sdk@0.8.53-pr.319.3e74a61"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/sdk": "npm:@base44-preview/sdk@0.8.53-pr.319.3e74a61"
  }
}

Preview published to npm registry — try new features instantly!

@ozsay ozsay mentioned this pull request Oct 12, 2026
2 of 4 tasks
@ozsay
ozsay force-pushed the feat/platform-server-webhooks branch from d85e70c to 9b2915b Compare October 12, 2026 11:41
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

🚀 Package Preview Available! (@base44/platform)


Install this PR's preview build with npm:

npm i @base44-preview/platform@0.1.0-pr.319.3e74a61

Prefer not to change any import paths? Install using npm alias so your code still imports @base44/platform:

npm i "@base44/platform@npm:@base44-preview/platform@0.1.0-pr.319.3e74a61"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "@base44/platform": "npm:@base44-preview/platform@0.1.0-pr.319.3e74a61"
  }
}

Preview published to npm registry — try new features instantly!

ozsay and others added 2 commits October 12, 2026 15:07
verifyEvent checks Standard Webhooks v1a (Ed25519, WebCrypto) signatures
and returns a typed event; handleChallenge answers the activation probe.
Event types are generated from the published JSON Schemas.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
createHandler returns a fetch-style route handler that verifies, answers
the activation challenge, dispatches per event type and maps outcomes to
status codes, with onEvent/onSuccess/onError callbacks. verifyEvent stays
for callers who dispatch themselves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ozsay
ozsay force-pushed the feat/platform-server-webhooks branch from f0a1592 to 75a4b1c Compare October 12, 2026 12:08
@ozsay
ozsay added this pull request to stack #321 October 12, 2026 12:08
…tory

createBase44PlatformServer keeps only the shared serverUrl/apiKey.
verifyEvent and createHandler now require publicKeys in their options.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant