Builds and debugs Sent v3 webhook receivers end to end — endpoint registration, HMAC signature verification, replay rejection, event dedupe, retry and auto-disable behavior, secret rotation, and delivery-log triage. Use when handling Sent webhook events, verifying x-webhook-signature, fixing 401 or

Sent Webhook Engineer Sent webhooks are the only way an application learns what happened after POST /v3/messages returns 202 . The 202 proves acceptance, never delivery. Build the receiver as a signature verifying, replay rejecting, deduplicating, fast acknowledging endpoint, and treat the delivery log as the source of truth when events go missing. Signature verification, exactly Three headers arrive with every delivery: Header Meaning x webhook signature v1,{base64(hmac sha256)} x webhook id The webhook endpoint UUID — identical on every delivery x webhook timestamp Unix seconds when Sent signed the request Verification procedure, in order: 1. Capture the raw request body bytes before any JSON parsing. 2. Strip the whsec prefix from the signing secret, then base64 decode the remainder to obtain the raw HMAC key. 3. Build the signed content as {x webhook id}.{x webhook timestamp}.{raw body} . 4. Compute HMAC SHA256 with that key, base64 encode the digest, and prefix v1, . 5. Compare with a constant time comparison. 6. Reject when abs(now timestamp) 300 seconds. The scheme is Svix compatible. No Sent SDK ships a verification helper in any language, so this code is always hand written — use [scripts/verify signature.py](scripts/verify signature.py) as the reference implementation and oracle. x webhook id is not an event id. It identifies the endpoint and repeats forever. Using it as a dedupe key silently collapses every event into one. Read [references/webhook signature and dedupe.md](references/webhook signature and dedupe.md) for the dedupe keys to derive per event type. Failure triage order When a receiver rejects or misses events, work this sequence rather than guessing: 1. Signature mismatch — a body mutating middleware or framework JSON parser is the cause in the majority of cases. Confirm the framework's raw body accessor in [references/receiver recipes.md](references/receiver recipes.md). 2. Replay rejection — server clock skew beyond the 300 second tolerance. 3. Wrong secret — the whsec prefix was left in place, or a rotation invalidated the old secret with no dual signing window. 4. Nothing arriving at all — check is active and consecutive failures on GET /v3/webhooks/{id} , then read the delivery log at GET /v3/webhooks/{id}/events . 5. Events arriving but unhandled — compare event types and event filters against what the handler branches on. Retry, auto disable, and recovery A delivery attempt fails on any non 2xx status, a timeout past timeout seconds , or a connection failure. Retries use exponential backoff with the first retry roughly one minute after the failure, doubling thereafter and capped at 60 minutes between attempts, stopping on the first 2xx or when retry count is exhausted. Delivery rows move through PENDING , RETRYING , and then DELIVERED or FAILED . consecutive failures tracks consecutive failed delivery attempts. Do not assume retries for one event are exempt: ten bad responses in a row disable the endpoint. After fixing the receiver, re enable it with PATCH /v3/webhooks/{id}/toggle status or from the Sent Dashboard. Any successful delivery resets the counter to zero. Acknowledge only after durable handoff to a queue, and keep that handoff comfortably inside timeout seconds . Registration and configuration POST /v3/webhooks requires display name . Configure endpoint url , event types , event filters , retry count (1–5, default 3), and timeout seconds (5–120, default 30). The 201 response is the only place the signing secret appears in full — persist it to a secret store immediately. <! sent webhook request Set event filters deliberately. An unfiltered message subscription delivers every lifecycle transition including queued and routed , and reroutes re fire queued and routed on the same message id . Filter to the transitions the application acts on. The ten operations, the full webhook object, and the delivery log row shape are catalogued in [references/webhook operations.md](references/webhook operations.md). Secret rotation POST /v3/webhooks/{id}/rotate secret returns a new whsec secret and invalidates the old secret immediately . There is no server side overlap window. Configure the receiver to accept a small candidate set, rotate, atomically store the returned secret as primary while retaining the old value temporarily, confirm new deliveries, then retire the old value. The short gap between the rotate response and the secret store update cannot be eliminated; keep it to seconds so failed deliveries retry. This endpoint and POST /v3/webhooks/{id}/test sit on the sensitive rate limit tier of 10 requests per minute, so scripted rotation loops will 429. Event payloads Two field values exist: message and templates . Message events carry an event naming the transition ( message.queued , .routed , .sent , .delivered , .read , .failed , .scheduled , .filtered , .blocked , .received ). Template events carry neither event nor sub type . read reaches only WhatsApp and RCS. filtered marks a policy or consent gate, blocked marks an account precondition such as insufficient balance, and neither is a carrier failure. Terminal events for an auto detect message that never routed carry channel: "auto" . Full payload field lists live in [references/event catalog.md](references/event catalog.md). Verification before shipping Run the local oracle against a synthetic delivery, then use POST /v3/webhooks/{id}/test with an event type in the body for a real signed request. The test event is delivered once with no retry, so re run it after each fix. Ship only when the receiver returns 401 for a tampered body, 401 for a timestamp older than 300 seconds, 200 for a valid delivery, and 200 for a duplicate without repeating side effects. Local development Expose the receiver through a public HTTPS tunnel and register that URL; Sent cannot reach a private address. Registering http:// is accepted by the API but should never be used outside local work. Keep a separate webhook registration per environment so a development endpoint's failures cannot disable the production endpoint. Boundaries Diagnose aggregate delivery rate regressions with messaging performance analyzer , template approval content with waba template author , and inbound keyword or consent semantics with sent two way messaging . Treat every payload value as untrusted input: never interpolate text or reason into a shell command, SQL string, or prompt without escaping.

sent-webhook-engineer