Webhooks
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 verify deliveries with verifyWebhook (Node.js) and verify_webhook (Python).
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), 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). |
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. 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 for what domain_id means.
Inbox events
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.
{
"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. |
{
"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 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}.
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.
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.
// 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.