sent-webhook-engineer

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 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 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.
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.