Receive delivery webhooks
Receive signed delivery updates without polling each message.
On this page
Workflow
- 1
Create an endpoint
Register a public HTTPS URL and choose the delivery events you need.
- 2
Store the signing secret
The secret is returned with the creation response. Keep it server-side.
- 3
Verify every request
Build the signed value from webhook-id, webhook-timestamp, and the exact raw request body.
- 4
Return a 2xx response
Acknowledge accepted events within 10 seconds. Retryable failures are delivered again.
Payload boundaries
- Includes message ID, status, sender, recipient, subject, timestamps, and failure details.
- Excludes message bodies, attachments, API keys, and internal delivery payloads.
Verify the signature
Compute Base64 HMAC-SHA256 over webhook-id.webhook-timestamp.raw-body with the endpoint signing secret, then compare it with the v1 value in webhook-signature using a constant-time comparison.
Reject stale timestamps and never parse or reserialize the JSON before verification.
Retries and disabling
RouteKite retries timeouts, 408, 425, 429, and server errors. A 410 response disables the endpoint immediately. Repeated failures can also disable an unhealthy endpoint.