Webhooks: signing, retries and replay

HMAC-SHA256 signed deliveries, three retries with backoff, then a dead-letter queue you can replay from.

Mails.ai — Webhooks: signing, retries and replay

Add an HTTPS endpoint, choose the events you want, and every matching event is POSTed to you.

The webhooks page listing an endpoint, its event types and its status

Verifying the signature

Each delivery carries X-Mails-Signature: an HMAC-SHA256 of the raw request body using your endpoint's signing secret, with a ±5 minute timestamp tolerance. Verify against the raw body, before any JSON parsing — a re-serialised body will not match, and that is the single most common integration bug here.

Retries

A non-2xx response or a timeout is retried three times with backoff. After that the delivery lands in the dead-letter queue, where it is kept and can be replayed once your endpoint is healthy again. Nothing is silently dropped.

Testing without waiting for real mail

webhook.test fires a synthetic delivery at your endpoint on demand, so you can confirm the signature check works before any customer mail depends on it. POST /v1/test/inbound goes further and pushes a fake inbound through the whole parse-and-classify path.

Endpoint counts are capped per plan: 5 on Free, 25 on Pro, 100 on Scale.

Add a webhook
Did this answer your question?
😞
😐
😁