Handle Stripe webhook events

POSThttps://app.speybooks.com/api/v1/webhooks/stripe

Receive and process Stripe webhook events. The processing flow is:

  1. Read the Stripe-Signature header; reject the delivery if it is missing.
  2. Verify the signature against the endpoint's signing secret using the unmodified request body.
  3. Open a transaction and consult the idempotency gate: a first sight is admitted, a duplicate conflicts.
  4. Already processed? Acknowledge and skip the delivery. Previously failed? Reprocess it.
  5. Dispatch to the handler for the event type. Subscription events pass the admission guard first: an unsupported status records an unsupported_status receipt and skips its handler, the mirror untouched. All writes ride the same transaction.
  6. Mark the event processed and commit; acknowledge the delivery.
  7. 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
receivedboolean
True 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.