Skip to main content
Every delivery is a signed POST of one frame, signed the Standard Webhooks way — an open specification with verifiers for most languages, so an off-the-shelf standardwebhooks library verifies it in three lines. Verify the signature, deduplicate on webhook-id, answer 2xx, and do the real work after you answer.

The request

The body is the delivered frame: the raw source frame plus subscriptionId. Route on subscriptionId — the channel alone does not tell two subscriptions of the same type apart.

What is signed

  • key comes from the subscription’s signing secret, the whsec_… value returned when you created it. Hand that string, as you received it, to a Standard Webhooks library: the library handles the key, so you do not compute the HMAC yourself.
  • raw_body is the request body exactly as received. Read it as bytes before any JSON parser touches it — parsing and re-serialising changes the bytes and the signature will not match.
A request is authentic when webhook-signature equals the signature you computed, compared in constant time, and webhook-timestamp is close to your clock — the libraries enforce a five-minute tolerance by default. Keep that check: it is what stops a captured delivery from being replayed at you later.

Known-answer test vector

Check your verifier against these exact Standard Webhooks inputs before you point it at live traffic. The timestamp is in 2023, so a verifier that enforces the tolerance against the real clock will reject it — pass a fixed “now” of 1700000000 in your test.

Verify with a library

The Standard Webhooks project publishes verifiers for most languages. Each takes the full whsec_… secret, the raw body and the request headers, checks the timestamp tolerance and the v1 signature, and throws or returns an error on a mismatch.
Hand the library the raw bytes: express.raw({ type: "application/json" }) on the webhook route in Express (as in the quickstart), await request.body() in FastAPI/Starlette, request.get_data() in Flask, io.ReadAll(r.Body) in Go. Reject the request with a 4xx when verification fails and never log the secret.

One secret per subscription

Each subscription has its own signing secret, generated when it is created and returned in the create response only. Read it again at any time with GET /v1/subscriptions/{id}/secret (reference); it is never in list responses. There is no rotation: a subscription’s secret lives as long as the subscription does. To change it, delete the subscription and create it again — the new one gets a new secret. If one receiver serves several subscriptions, look up the secret by the body’s subscriptionId — or, simpler, give each subscription its own URL path. An inbox subscription has no secret: nothing is POSTed, so nothing is signed, and GET /v1/subscriptions/{id}/secret answers 400 for it. You read its messages over the authenticated API instead of verifying them.

Acknowledgement and retries

A delivery succeeds on any 2xx. Anything else — another status, a timeout, a refused connection — is a failure and is retried on a bounded back-off, up to nine attempts over about 76 hours. A Retry-After header on your response is respected, up to 24 hours. When the attempts run out the delivery is dropped. Two things follow from how retries are kept:
  • Ordinary deliveries and their retries live in memory. A restart of the service loses them, and nothing is replayed — see no delivery after a restart. Only priceCross, cohort bias and liquidation risk deliveries use a durable outbox that survives restarts.
  • The queue is bounded: 128 fresh deliveries plus 128 waiting retries across all subscriptions, each at most 1 MiB, and at most 16 slots for any one subscription across both pools. A retry waits in its own pool, so a failing receiver’s back-off never holds a slot a fresh delivery could use; when a pool is full, further retries are dropped and logged, and a saturated subscription drops its own frames without taking another subscription’s share. The numbers are on Plan limits.
Delivery is at least once, and order across workers and retries is not guaranteed: a retry can arrive after a newer frame. Deduplicate on webhook-id and order by seq within one source if order matters.

410 disables the subscription

A 410 Gone response disables the subscription at once: deliveries stop and it shows disabled: true in GET /v1/subscriptions. Frames matched while it is disabled are not kept. Re-enable it with POST /v1/subscriptions/{id}/enable, which is idempotent and answers 429 if the account is already at its subscription allowance — a disabled subscription does not count toward the allowance, so enabling one can put you over it. Return 410 only when you mean to stop the subscription.

Transport rules

  • Public HTTPS on port 443. Nothing else is accepted when you create the subscription.
  • No redirects. A 3xx is refused; register the final URL.
  • No private or reserved addresses. Loopback, private, link-local and similar ranges are refused at creation.
  • Answer first, then process: push the frame onto your own queue and return 200. There is no replay, so a slow handler that times out costs you a retry at best and a dropped delivery at worst.