---
title: Webhooks
description: Signed event deliveries to your endpoint, with retries and a delivery log.
---

A webhook sends an HTTP `POST` to your endpoint each time something happens: an email is delivered, a contact unsubscribes, mail arrives. Add endpoints in the dashboard under **Webhooks**, or with `POST /webhooks`, and choose which events each one receives. The [SDKs](/docs/sdks) verify deliveries with `verifyWebhook` (Node.js) and `verify_webhook` (Python).

```sh
curl -X POST "https://api.billionsend.com/webhooks" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://example.com/webhooks/email",
    "events": ["email.delivered", "email.bounced"]
  }'
```

The response carries the `signing_secret` (`whsec_...`). `GET /webhooks/{id}` returns it again, and list rows never include it.

## Events

### Email events

| Event | Fired when |
| --- | --- |
| `email.scheduled` | An email was accepted with a `scheduled_at` in the future. |
| `email.sent` | The email was handed to the mail service. |
| `email.delivered` | The recipient's server accepted it. |
| `email.delivery_delayed` | Delivery is being retried (full mailbox, greylisting). |
| `email.bounced` | The email bounced. `data.bounce.type` is `Permanent` (a hard bounce: the address is also [suppressed](/docs/concepts/suppressions)), `Transient` or `Undetermined` (not suppressed). |
| `email.complained` | The recipient marked it as spam. The address is also suppressed. |
| `email.failed` | The email will never be sent. `data.failed.reason` says why. |
| `email.suppressed` | The email was stopped before sending. `data.suppressed.reason` says why. |
| `email.opened` | A person opened it (needs open tracking on the [domain](/docs/concepts/domains)). |
| `email.clicked` | A person clicked a tracked link (needs click tracking). |
| `email.prefetched` | A machine, not a person, loaded the tracking pixel or followed a link (privacy proxies, security scanners). Opt-in, see below. |
| `email.received` | A message reached one of your [receiving domains](/docs/receiving). `data.email_id` is read with `GET /emails/receiving/{id}`. |

`email.prefetched` is opt-in, like every `inbox.*` event: an endpoint gets it only when it names the event, never through "all events".

### Account events

These carry no email. `data` describes your team's standing.

| Event | Fired when |
| --- | --- |
| `deliverability.warning` | Your hard-bounce or complaint rate crossed the warning line. |
| `deliverability.paused` | The rate crossed the pause line, and new sends are refused until it recovers. |
| `quota.warning` | 80% of your quota is used (today's limit on Free, the billing period's included volume on paid plans). |
| `quota.reached` | The quota is used up. |
| `quota.paused` | Free only: sends are held until midnight UTC or until you upgrade. |

### Audience events

They fire whenever a contact or the suppression list changes, whoever changed it. `data` holds the contact (`id`, `email`, `first_name`, `last_name`, `unsubscribed`, `created_at`, `updated_at`) and a `source`: `api`, `dashboard`, `hosted_page` or `one_click`.

| Event | Fired when | Extra `data` |
| --- | --- | --- |
| `contact.created` | A contact was added. | |
| `contact.updated` | Name, properties or the unsubscribed flag changed. | |
| `contact.deleted` | A contact was deleted. After an erasure the `email` reads `[erased]`, so key on `id`. | |
| `contact.unsubscribed` | A recipient used an unsubscribe link, or you set `unsubscribed` to `true`. | `domain_id`, `domain_name` (both `null` for a whole-team opt-out) |
| `contact.resubscribed` | An opt-out was taken back. | `domain_id`, `domain_name` |
| `contact.topic_opt_in`, `contact.topic_opt_out` | A contact's subscription to a topic changed. | `topic_id`, `topic_name` |
| `suppression.added`, `suppression.removed` | An address joined or left the suppression list. | `id`, `email`, `origin`, `source`, `source_id`, `created_at` |

See [Unsubscribes](/docs/concepts/unsubscribes) for what `domain_id` means.

### Inbox events

[Inboxes](/docs/inboxes) send `inbox.created`, `inbox.updated`, `inbox.deleted`, `inbox.expired`, `inbox.thread.created`, `inbox.thread.folder.updated`, `inbox.thread.labels.updated`, `inbox.email.received`, `inbox.email.sent`, `inbox.email.quarantined`, `inbox.draft.created`, `inbox.draft.updated`, `inbox.draft.sent`, `inbox.draft.deleted` and `inbox.draft.send_failed` (a scheduled send was refused; BillionSend's own, with the draft and `error: { name, message }`). All are opt-in.

`data` always has `source` (`api`, `dashboard` or `system`) and `inbox_id`. Email and draft objects never carry the body: fetch it with the API.

To limit an endpoint to some inboxes, send `inbox_ids` (up to 100 inboxes of your team; `null` means every inbox, an empty list none). In the dashboard it is **Only these inboxes**.

### Payloads

Every email event carries `email_id`, `from`, `to`, `subject` and `created_at`, plus `tags` when you sent the email with tags.

```json title="email.failed"
{
  "type": "email.failed",
  "created_at": "2026-10-13T10:00:02.317Z",
  "data": {
    "email_id": "3f7b2c71-5274-4246-82f3-57bc1563c276",
    "from": "Acme <billing@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your receipt",
    "created_at": "2026-10-13T10:00:02.317Z",
    "failed": { "reason": "domain_not_verified" }
  }
}
```

| `failed.reason` | What happened |
| --- | --- |
| `domain_not_verified` | The sending domain was not verified when the email went out. |
| `domain_deleted` | The sending domain was deleted while the email waited. |
| `held_for_review_expired` | The email was held for a safety check and not released within 7 days. |
| `team_suspended` | The team was suspended and not reinstated within 7 days of the email being held. |
| `broadcasts_paused` | The team's broadcasts were paused and not resumed within 7 days of the email being held. |
| `ses_tenant_paused` | SES paused sending for the team and did not lift the pause within 7 days. |
| `body_missing`, `body_unreadable` | The stored content was missing or could not be read, for example because the email was still held when its content passed the retention window. |
| `message_rejected` | The mail service refused the message, for example because it carried a virus. |
| `retries_exhausted` | Every send attempt failed on a temporary error. |
| `send_interrupted` | A send was cut off before it was confirmed, so the email may or may not have gone out. It is not tried again. |
| `provider_error` | Any other error that stopped the send. |

```json title="email.suppressed"
{
  "type": "email.suppressed",
  "created_at": "2026-10-14T09:30:00.912Z",
  "data": {
    "email_id": "b10f77bb-a99a-48c9-bd0a-a5d2cb1ba4a1",
    "from": "Acme <hello@example.com>",
    "to": ["ada@example.org"],
    "subject": "Your trial ends tomorrow",
    "created_at": "2026-10-14T09:30:00.912Z",
    "suppressed": {
      "type": "OnAccountSuppressionList",
      "message": "The recipient is on your suppression list.",
      "reason": "recipient_suppressed"
    }
  }
}
```

| `suppressed.reason` | Meaning |
| --- | --- |
| `recipient_suppressed` | The address is on your suppression list. |
| `contact_unsubscribed` | The contact is unsubscribed team-wide. |
| `domain_unsubscribed` | The recipient unsubscribed from this sending domain. |
| `topic_unsubscribed` | The recipient opted out of the email's topic. |
| `contact_missing`, `contact_recipient_mismatch` | The contact was deleted, or its address changed, before the email went out. |
| `broadcast_missing`, `topic_missing` | The broadcast or topic was deleted before the email went out. |
| `ineligible` | Any other reason the email was no longer eligible. |

If only some recipients are dropped, the email goes to the rest and no `email.suppressed` fires. Canceling a broadcast fires nothing for the emails it stops.

## Verify the signature

Deliveries follow the [Standard Webhooks](https://www.standardwebhooks.com) scheme. Each request carries:

```
webhook-id: <message id>
webhook-timestamp: <unix seconds>
webhook-signature: v1,<base64 HMAC-SHA256>
```

The same values are also sent as `svix-id`, `svix-timestamp` and `svix-signature`, so a handler written for either header family works unchanged. The signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`.

```ts
import { Webhook } from "standardwebhooks";

const wh = new Webhook("whsec_...");
const event = wh.verify(rawBody, {
  "webhook-id": req.headers["webhook-id"],
  "webhook-timestamp": req.headers["webhook-timestamp"],
  "webhook-signature": req.headers["webhook-signature"],
});
```

Always verify against the raw request body, and reject old timestamps.

## Secrets

**Bring your own.** `POST /webhooks` accepts `signing_secret`: `whsec_` followed by base64 of 24 to 64 bytes. Pass the secret your receiver already uses and the endpoint keeps working without a redeploy. Anything else returns `422`.

**Rotate.** `POST /webhooks/{id}/rotate`, or **Rotate secret** in the dashboard, creates a new secret (or takes the one in `signing_secret`) and returns it. For `overlap_hours` (default 24, up to 72) the old secret keeps signing too, so each delivery carries two signatures and a receiver with either secret verifies it. Switch your receiver at any point in the window. `0` drops the old secret at once, which is what you want for a leaked one. `GET /webhooks/{id}` shows when the window ends as `previous_secret_expires_at`.

```sh
curl -X POST "https://api.billionsend.com/webhooks/$WEBHOOK_ID/rotate" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "overlap_hours": 24 }'
```

## Delivery and retries

Answer with any `2xx` status and the delivery counts as successful. Each endpoint has its own queue, which sends up to 50 requests per second.

A failed attempt (non-2xx, timeout, connection error) is retried after **5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours and 10 hours**: six attempts over about 18 hours. A `429` with a `Retry-After` header is honored (up to one hour) and does not count as an attempt. An event still undelivered 24 hours after it was queued is dropped.

After **20 failed deliveries in a row**, the endpoint is disabled automatically (status `auto_disabled`) and receives nothing until you enable it again. Events that happened in between are not replayed. The team's owners get an email when deliveries start failing, when an endpoint is disabled, and at most once a day when its backlog is more than six hours old.

Delivery is at least once, and events are not delivered in order. The same event can arrive more than once, and events can arrive in a different order from the one they happened in: an `email.delivered` can come before the `email.sent` of the same email. Make your handler idempotent, keyed on `webhook-id`, and order an email's events by the payload's `created_at` (when the event happened), never by arrival. One exception: `email.failed` with reason `send_interrupted` is a guess, and an `email.sent`, `email.delivered` or other outcome for the same email replaces it even when its `created_at` is earlier.

```ts
// event: the verified payload; webhookId: the webhook-id header.
if (await alreadyHandled(webhookId)) return; // a repeat delivery
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } or null
const newer = !known || at > known.at || known.guess;
if (newer) {
  const guess = event.type === "email.failed" && event.data.failed.reason === "send_interrupted";
  await db.setEmailStatus(event.data.email_id, { status: event.type, at, guess });
}
await markHandled(webhookId);
```

## Delivery log

Open an endpoint in the dashboard to see every delivery: the event, the payload, your response and each attempt, kept for 30 days. You can press **Retry now** on a delivery, and **Send test event** to try the endpoint. The page also shows the endpoint's queue size and how long its oldest delivery has been waiting.

## Limits

| | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Webhook endpoints per team | 1 | No limit |

Past the limit, `POST /webhooks` returns `403 plan_limit_reached`. After a downgrade, existing endpoints keep working but you cannot add more. Subscribe each endpoint only to the events it needs: an endpoint on "all events" gets one `contact.created` for every contact you import.
