Skip to main content
Not yet released. The packages on this page are not published to npm yet, so the install commands below will not resolve. The documented interface is stable and the code exists; only publication is outstanding. To use KeyStone from a frontend today, call the REST API or the TypeScript SDK, which is published. Contact us if you need early access.

Import

Express Middleware

The easiest way to handle webhooks in Express:
You must use express.raw() (not express.json()) so the middleware receives the raw body for signature verification.

Parameters

Behavior

  • Reads X-Keystone-Signature header
  • Verifies HMAC-SHA256 signature using timing-safe comparison
  • Parses the JSON body
  • Attaches parsed event to req.keystoneEvent
  • Returns 401 if signature is invalid or missing

Manual Verification

For non-Express frameworks (Hono, Fastify, serverless), use the lower-level functions:

verifyAndParseWebhook

Returns the parsed WebhookEvent or null if verification fails.

verifyWebhookSignature

Signature verification only, without JSON parsing:
Returns true if the signature is valid.

WebhookEvent Type

Common Events

See the webhook event catalog for the full list and which states emit events.