# Webhooks

Receive real-time notifications when email events occur.

## Event types

- **message.received** — A new inbound email arrived
- **message.sent** — An outbound email was accepted for delivery
- **message.delivered** — An outbound email was delivered to the recipient
- **message.bounced** — An outbound email permanently bounced
- **message.complaint** — A recipient marked the email as spam


## Delivery & retries

Webhook payloads are POST requests to your endpoint URL (must be HTTPS). Each delivery includes a JSON body with the event type, timestamp, and relevant data.

If your endpoint returns a non-2xx status, Robotomail retries with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours. After 10 consecutive failures, the webhook is automatically paused with status `FAILED`.


## Signature verification

Every webhook delivery includes an `X-Robotomail-Signature` header containing an HMAC-SHA256 signature of the request body. Verify it against the webhook secret returned when you created the webhook.

See the [Webhooks API reference](https://robotomail.com/docs/api/webhooks) or the [Receive & reply guide](https://robotomail.com/docs/guides/receive-and-reply) for verification examples. The secret is only returned once at creation time.


## Custom headers

You can attach custom HTTP headers to a webhook that are included in every delivery request. This is useful for passing authentication tokens, routing keys, or other metadata your endpoint requires.

Pass a `headers` object when creating or updating a webhook. Up to 10 headers are allowed (key max 256 chars, value max 1024 chars). Header names must be valid HTTP tokens — spaces, colons, and other non-token characters are rejected. Values must not contain control characters (prevents CRLF injection). Headers with the `X-Robotomail-` prefix are reserved and will be rejected. Dangerous headers (`Host`, `Content-Length`, `Content-Type`, `Transfer-Encoding`, `Connection`, `Keep-Alive`, `Upgrade`, `TE`, `Trailer`) are also blocked. To clear all custom headers, pass `null` in a PATCH request.


## Webhook scoping

Webhooks can be **account-level** (triggered for events on any mailbox) or **mailbox-scoped** (triggered only for events on a specific mailbox). Scoped API keys can only create mailbox-scoped webhooks for mailboxes in their scope.


---

Previous: [Threading](https://robotomail.com/docs/concepts/threading.md) | Next: [Domains](https://robotomail.com/docs/concepts/domains.md)