Handle Stripe webhook events
POST
https://app.speybooks.com/api/v1/webhooks/stripeReceive and process Stripe webhook events. The processing flow is:
- Read the
Stripe-Signatureheader; reject the delivery if it is missing. - Verify the signature against the endpoint's signing secret using the unmodified request body.
- Open a transaction and consult the idempotency gate: a first sight is admitted, a duplicate conflicts.
- Already processed? Acknowledge and skip the delivery. Previously failed? Reprocess it.
- Dispatch to the handler for the event type. Subscription events
pass the admission guard first: an unsupported status records an
unsupported_statusreceipt and skips its handler, the mirror untouched. All writes ride the same transaction. - Mark the event processed and commit; acknowledge the delivery.
- On handler failure: roll back, record the failure in the gate ledger, and signal Stripe to redeliver, which is the recovery path.
Signature verification requires the unmodified request body, so this endpoint receives the raw payload rather than a parsed one.
Response
200Webhook processed, or recognised as an already-processed duplicate delivery and skipped (idempotency gate).
Show response fields
receivedbooleanTrue when the event has been processed or safely skipped.
Error codes
400Missing Stripe signature header or webhook signature verification failed.
500Handler processing failed. The transaction is rolled back, the event is recorded as failed, and the non-2xx response invites Stripe’s retry, which reprocesses through the idempotency gate.