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
keycomes from the subscription’s signing secret, thewhsec_…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_bodyis 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.
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” of1700000000 in your test.
Verify with a library
The Standard Webhooks project publishes verifiers for most languages. Each takes the fullwhsec_… 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.
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 withGET /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. ARetry-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.
webhook-id and order by seq within one source if order matters.
410 disables the subscription
A410 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
3xxis 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.

