Skip to main content

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.