StripeKit - Webhook Process

`kit.webhooks.process()`

Verifies a raw webhook payload against your webhookSecret, deduplicates it by Stripe event ID, automatically re-syncs the relevant object into your storage adapter, and then calls whichever of your handlers matches the event type.

Signature

Parameters

Field	Type	Required	Description
`payload`	`string`	Yes	The raw, unparsed request body. Do not `JSON.parse()` it first; Stripe's signature is computed over the exact raw bytes.
`signature`	`string`	Yes	The value of the `Stripe-Signature` request header.
`handlers`	`Record<string, Handler>`	No	Keyed by handler name, see Events reference for every available key.
`autoSync`	`boolean`	No, defaults to `true`	If `false`, StripeKit skips its own automatic re-sync step entirely and only calls your handler.

Example request

Example response

For an event StripeKit has already processed before (same eventId):

When duplicate is true, no handler is called and no sync happens; StripeKit stops immediately after detecting the event was already seen.

Handler function signature

Every handler receives two arguments:

Errors

Exception	When
`ConfigurationError`	`webhookSecret` was not configured on `StripeKit.init()`.
`WebhookVerificationError`	The signature does not match the payload, meaning the request did not genuinely come from Stripe (or the raw body was altered, for example by JSON-decoding and re-encoding it before calling `process()`). Return HTTP 400 for this.
Anything your own handler throws	`process()` re-throws whatever your handler throws, after logging it. The event is still marked as processed by that point, so a throwing handler will not cause Stripe to see a duplicate delivery attempt as new.

Notes

Always pass the raw request body, never a re-encoded one. In most Node setups this is the raw buffer from the request before any middleware has touched or parsed it.

Return HTTP 200 for every successfully processed event, including duplicates, so Stripe stops retrying delivery. Only return a non-200 status when process() itself throws.

See Events reference for exactly which handler key maps to which Stripe event type, and what StripeKit syncs automatically for each one.

See Storage adapter for what happens to webhook idempotency (hasProcessedWebhookEvent / markWebhookEventProcessed) when no storage adapter is configured.

Process

kit.webhooks.process()#

Signature#

Parameters#

Example request#

Example response#

Handler function signature#

Errors#

Notes#