#Webhooks reference

#Delivery

• POST to your URL with Content-Type: application/json and the event envelope.
• Headers (Standard Webhooks, https://www.standardwebhooks.com/):
  • webhook-id — the event id (stable across retries and replays),
  • webhook-timestamp — Unix seconds,
  • webhook-signature — v1,<base64 HMAC-SHA256> of "{webhook-id}.{webhook-timestamp}.{raw body}" keyed with the base64-decoded part of your whsec_... secret.
• Answer with any 2xx within 10 seconds. Redirects are not followed.

#Verifying

Use the SDK's verifyWebhook(secret, rawBody, headers) or any Standard Webhooks library (available for many languages). Verify against the raw bytes, reject timestamps older than 5 minutes (the libraries do), compare in constant time.

#Retries

Non-2xx, timeouts and connection errors are retried with exponential backoff: 8 attempts starting at 30 seconds (30 s, 1 m, 2 m, 4 m, … ≈ 2 hours in total). Each attempt is visible in the delivery log (GET /v1/webhook-deliveries): status, attempts, response status and the first 2 KB of your response. Disabled endpoints receive nothing.

#Replay

POST /v1/webhook-deliveries/{id}/replay sends the same event again as a new delivery (same webhook-id). POST /v1/webhook-endpoints/{id}/test sends a webhook.test event.

#Ordering and duplicates

Delivery is at-least-once. Events of one call are created in order, but retries can reorder deliveries — use data.status and the timestamps, and deduplicate on id.

#Security

In production webhook URLs must be https and resolve to public addresses. Rotate the secret with POST /v1/webhook-endpoints/{id}/rotate-secret (the old secret stops working immediately).