Webhooks API

Contracts for event ingestion, controlled replay, and operational traceability.

reference • updated 2026-03-15

Goal

Ingest Stripe events with signature verification, event-level deduplication, and controlled replay for incident recovery.

Primary endpoints

Endpoint	Usage	Security
`POST /v1/webhooks/stripe`	general Stripe event intake	Stripe signature required
`POST /v1/webhooks/stripe/billing`	billing/subscription-specific events	Stripe signature required

Processing model

11) Receive event
Validate signature and minimum payload shape.
22) Deduplicate
Use provider event.id as the logical idempotency key.
33) Queue processing
Run async handlers with safe retry semantics.
44) Confirm state
Update business state and delivery metrics.

Received event example

json

{
  "id": "evt_123",
  "type": "invoice.paid",
  "created": 1710492000,
  "data": {
    "object": {
      "id": "in_123",
      "customer": "cus_123"
    }
  }
}

Retry and replay policy

Automatic retries must preserve original event context.
Manual replay must be scoped by time window and organization.
Avoid broad replay operations without impact prioritization and explicit validation criteria.

Operational signals

Signal	Meaning	Action
rising `4xx`	signature/payload mismatch	rotate secret if needed and revalidate contract
growing backlog	slow or blocked consumer	increase throughput and prioritize critical events
duplicated side effects	incomplete deduplication	harden dedupe key by `event.id` + organization