Sent Webhook Engineer
Sent webhooks are the only way an application learns what happened after
returns
. The
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 |
|---|
| |
| The webhook endpoint UUID — identical on every delivery |
| Unix seconds when Sent signed the request |
Verification procedure, in order:
- Capture the raw request body bytes before any JSON parsing.
- Strip the prefix from the signing secret, then base64-decode the remainder to obtain the raw HMAC key.
- Build the signed content as
{x-webhook-id}.{x-webhook-timestamp}.{raw_body}
- Compute HMAC-SHA256 with that key, base64-encode the digest, and prefix .
- Compare with a constant-time comparison.
- Reject when
abs(now - timestamp) > 300
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.
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:
- 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.
- Replay rejection — server clock skew beyond the 300-second tolerance.
- Wrong secret — the prefix was left in place, or a rotation invalidated the old secret with no dual-signing window.
- Nothing arriving at all — check and on , then read the delivery log at
GET /v3/webhooks/{id}/events
- Events arriving but unhandled — compare and against what the handler branches on.
Retry, auto-disable, and recovery
A delivery attempt fails on any non-2xx status, a timeout past
, 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
is exhausted. Delivery rows move through
,
, and then
or
.
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
.
Registration and configuration
requires
. Configure
,
,
,
(1–5, default 3), and
(5–120, default 30). The
response is the only place the
appears in full — persist it to a secret store immediately.
<!-- sent-webhook-request -->
json
{
"display_name": "Production delivery events",
"endpoint_url": "https://hooks.example.com/webhooks/sent",
"event_types": ["message", "templates"],
"event_filters": {
"message": ["delivered", "failed", "received"]
},
"retry_count": 3,
"timeout_seconds": 30
}
Set
deliberately. An unfiltered
subscription delivers every lifecycle transition including
and
, and reroutes re-fire
and
on the same
. 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.
Secret rotation
POST /v3/webhooks/{id}/rotate-secret
returns a new
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
values exist:
and
. Message events carry an
naming the transition (
,
,
,
,
,
,
,
,
,
). Template events carry neither
nor
.
json
{
"field": "templates",
"value": {
"account_id": "3f1a7c22-5d8e-4b90-91a2-6c4d0e8f7b31",
"template_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
"template_name": "order_confirmation",
"whatsapp_template_id": "",
"status": "PENDING",
"language": "en_US",
"category": "UTILITY",
"channel": "whatsapp"
}
}
reaches only WhatsApp and RCS.
marks a policy or consent gate,
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
. Full payload field lists live in
references/event-catalog.md.
Verification before shipping
Run the local oracle against a synthetic delivery, then use
POST /v3/webhooks/{id}/test
with an
in the body for a real signed request. The test event is delivered once with no retry, so re-run it after each fix.
bash
python3 scripts/verify_signature.py --self-test
Ship only when the receiver returns
for a tampered body,
for a timestamp older than 300 seconds,
for a valid delivery, and
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
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
, and inbound keyword or consent semantics with
. Treat every payload value as untrusted input: never interpolate
or
into a shell command, SQL string, or prompt without escaping.