Webhooks: events, payloads and signatures

Scopes: webhooks:read and webhooks:write.

Endpoints

• GET /webhooks — list endpoints
• POST /webhooks — create an endpoint
• PATCH /webhooks/{webhook_id} — update an endpoint
• DELETE /webhooks/{webhook_id} — delete an endpoint
• GET /webhooks/{webhook_id}/deliveries — delivery history

Supported events

email.sent, email.delivered, email.opened, email.clicked, email.bounced, email.failed, email.unsubscribed, reply.received, campaign.launched, campaign.completed, campaign.paused, contact.created, contact.updated, contact.replied.

Headers on every delivery

• x-munchreach-event — the event name
• x-munchreach-delivery — a unique delivery id
• x-munchreach-timestamp — the Unix timestamp that was signed
• x-munchreach-signature — v1=<hex HMAC-SHA256>

Verifying a signature

Compute HMAC-SHA256 over the exact string v1:<timestamp>:<raw body> using your endpoint secret, and compare it to the hex value after v1= with a constant-time comparison. Verify against the raw body bytes, before any JSON parsing. Reject deliveries whose timestamp is far from your clock — that is what stops replays.

Retries

A delivery is retried when your endpoint does not return a 2xx. Backoff is 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, then 24 hours.

Important notes

Respond 2xx quickly and process asynchronously. A slow handler causes timeouts, which look like failures and trigger retries.