---
title: Webhook
description: 向你的端点发送带签名的事件通知，支持重试，并提供投递日志。
seo:
  title: 邮件 Webhook
ai:
  exclude: true
---

每当有事情发生时，Webhook 都会向你的端点发送一个 HTTP `POST` 请求：邮件已送达、联系人退订、收到新邮件等。在控制台的 **Webhook** 中添加端点，或使用 `POST /webhooks`，并为每个端点选择要接收的事件。[SDK](/docs/zh-hans/sdks) 用 `verifyWebhook`（Node.js）和 `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"]
  }'
```

响应中带有 `signing_secret`（`whsec_...`）。`GET /webhooks/{id}` 会再次返回它，列表中的各行从不包含它。

## 事件

### 邮件事件

| 事件 | 触发时机 |
| --- | --- |
| `email.scheduled` | 邮件已被接受，且 `scheduled_at` 在未来。 |
| `email.sent` | 邮件已交给邮件服务。 |
| `email.delivered` | 收件人的服务器已接受。 |
| `email.delivery_delayed` | 正在重试投递（邮箱已满、灰名单）。 |
| `email.bounced` | 邮件被退信。`data.bounce.type` 为 `Permanent`（硬退信：该地址也会被 [抑制](/docs/zh-hans/concepts/suppressions)）、`Transient` 或 `Undetermined`（不会被抑制）。 |
| `email.complained` | 收件人把它标记为垃圾邮件。该地址也会被抑制。 |
| `email.failed` | 邮件永远不会被发送。`data.failed.reason` 说明原因。 |
| `email.suppressed` | 邮件在发送前被拦截。`data.suppressed.reason` 说明原因。 |
| `email.opened` | 有人打开了邮件（需要在 [域名](/docs/zh-hans/concepts/domains) 上开启打开追踪）。 |
| `email.clicked` | 有人点击了被追踪的链接（需要开启点击追踪）。 |
| `email.prefetched` | 是机器而不是真人加载了追踪像素或访问了链接（隐私代理、安全扫描器）。需主动订阅，见下文。 |
| `email.received` | 有邮件到达你的某个 [收信域名](/docs/zh-hans/receiving)。`data.email_id` 可用 `GET /emails/receiving/{id}` 读取。 |

`email.prefetched` 与每个 `inbox.*` 事件一样需要主动订阅：端点只有在明确列出该事件时才会收到它，选择「全部事件」也不会收到。

### 账户事件

这些事件不涉及邮件。`data` 描述你的团队的状态。

| 事件 | 触发时机 |
| --- | --- |
| `deliverability.warning` | 你的硬退信率或投诉率越过了警告线。 |
| `deliverability.paused` | 比率越过了暂停线，在恢复之前新的发送会被拒绝。 |
| `quota.warning` | 已用掉 80% 的额度（Free 套餐为当天的上限，付费套餐为计费周期内包含的发送量）。 |
| `quota.reached` | 额度已用完。 |
| `quota.paused` | 仅限 Free：发送会暂扣到 UTC 午夜，或直到你升级。 |

### 受众事件

只要联系人或抑制列表发生变化就会触发，不论是谁改的。`data` 包含联系人（`id`、`email`、`first_name`、`last_name`、`unsubscribed`、`created_at`、`updated_at`）和一个 `source`：`api`、`dashboard`、`hosted_page` 或 `one_click`。

| 事件 | 触发时机 | 额外的 `data` |
| --- | --- | --- |
| `contact.created` | 添加了联系人。 | |
| `contact.updated` | 姓名、属性或退订标记发生变化。 | |
| `contact.deleted` | 联系人被删除。擦除之后 `email` 显示为 `[erased]`，所以请以 `id` 为键。 | |
| `contact.unsubscribed` | 收件人使用了退订链接，或你把 `unsubscribed` 设为 `true`。 | `domain_id`、`domain_name`（整个团队退订时两者都为 `null`） |
| `contact.resubscribed` | 撤销了一次退订。 | `domain_id`、`domain_name` |
| `contact.topic_opt_in`、`contact.topic_opt_out` | 联系人对某个订阅主题的订阅发生变化。 | `topic_id`、`topic_name` |
| `suppression.added`、`suppression.removed` | 一个地址加入或离开了抑制列表。 | `id`、`email`、`origin`、`source`、`source_id`、`created_at` |

`domain_id` 的含义参见 [退订](/docs/zh-hans/concepts/unsubscribes)。

### 收件箱事件

[收件箱](/docs/zh-hans/inboxes) 会发送 `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` 和 `inbox.draft.send_failed`（定时发送被拒绝；这是 BillionSend 自己的事件，带有草稿和 `error: { name, message }`）。所有这些都需要主动订阅。

`data` 中始终有 `source`（`api`、`dashboard` 或 `system`）和 `inbox_id`。邮件和草稿对象从不包含正文：请通过 API 获取。

要把一个端点限定在部分收件箱，请发送 `inbox_ids`（最多 100 个你团队的收件箱；`null` 表示所有收件箱，空列表表示一个都不要）。在控制台中对应的是 **仅这些收件箱**。

### 载荷

每个邮件事件都带有 `email_id`、`from`、`to`、`subject` 和 `created_at`，发送邮件时带了标签的话还有 `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": ["success@simulator.amazonses.com"],
    "subject": "Your receipt",
    "created_at": "2026-10-13T10:00:02.317Z",
    "failed": { "reason": "domain_not_verified" }
  }
}
```

| `failed.reason` | 发生了什么 |
| --- | --- |
| `domain_not_verified` | 邮件发出时，发信域名尚未验证。 |
| `domain_deleted` | 邮件在等待期间，发信域名被删除。 |
| `held_for_review_expired` | 邮件因安全检查被暂扣，7 天内没有被放行。 |
| `team_suspended` | 团队被停用，在邮件被暂扣后的 7 天内没有恢复。 |
| `broadcasts_paused` | 团队的群发被暂停，在邮件被暂扣后的 7 天内没有恢复。 |
| `ses_tenant_paused` | SES 暂停了该团队的发送，7 天内没有解除暂停。 |
| `body_missing`、`body_unreadable` | 存储的内容丢失或无法读取，例如邮件仍被暂扣时，它的内容已超过保留期。 |
| `message_rejected` | 邮件服务拒绝了该邮件，例如因为它带有病毒。 |
| `retries_exhausted` | 每次发送尝试都因临时错误而失败。 |
| `send_interrupted` | 发送在确认之前被中断，所以邮件可能已发出，也可能没有。不会再次尝试。 |
| `provider_error` | 其他任何使发送中止的错误。 |

```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": ["success@simulator.amazonses.com"],
    "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` | 含义 |
| --- | --- |
| `recipient_suppressed` | 该地址在你的抑制列表中。 |
| `contact_unsubscribed` | 该联系人对整个团队退订。 |
| `domain_unsubscribed` | 收件人已从该发信域名退订。 |
| `topic_unsubscribed` | 收件人已退出该邮件的订阅主题。 |
| `contact_missing`、`contact_recipient_mismatch` | 联系人在邮件发出之前被删除，或它的地址发生了变化。 |
| `broadcast_missing`、`topic_missing` | 群发或订阅主题在邮件发出之前被删除。 |
| `ineligible` | 邮件不再符合发送条件的其他任何原因。 |

如果只有部分收件人被剔除，邮件会发给其余的收件人，不会触发 `email.suppressed`。取消群发时，被它停止的邮件不会触发任何事件。

## 验证签名

投递遵循 [Standard Webhooks](https://www.standardwebhooks.com) 方案。每个请求都带有：

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

同样的值也会以 `svix-id`、`svix-timestamp` 和 `svix-signature` 发送，所以为任一套请求头编写的处理程序都能直接使用。被签名的内容是 `{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"],
});
```

务必对原始请求体进行验证，并拒绝过旧的时间戳。

## 密钥

**使用你自己的密钥。** `POST /webhooks` 接受 `signing_secret`：`whsec_` 后面跟 24 到 64 个字节的 base64。传入你的接收方已在使用的密钥，端点无需重新部署就能继续工作。其他任何格式都返回 `422`。

**轮换。** `POST /webhooks/{id}/rotate`，或控制台中的 **轮换密钥**，会创建一个新密钥（或使用 `signing_secret` 中传入的密钥）并返回它。在 `overlap_hours`（默认 24，最多 72）期间，旧密钥仍会继续签名，所以每次投递带有两个签名，使用任一密钥的接收方都能验证通过。你可以在这个时间窗口内的任意时刻切换接收方。设为 `0` 会立即丢弃旧密钥，密钥泄露时应该这样做。`GET /webhooks/{id}` 会以 `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 }'
```

## 投递与重试

返回任何 `2xx` 状态码，该次投递就算成功。每个端点都有自己的队列，每秒最多发送 50 个请求。

失败的尝试（非 2xx、超时、连接错误）会在 **5 秒、5 分钟、30 分钟、2 小时和 5 小时** 后重试。总共六次尝试，历时约 7 小时 35 分钟，第六次仍失败的投递会被放弃。带有 `Retry-After` 头的 `429` 会被遵守（最长一小时），且不计为一次尝试。入队 24 小时后仍未投递的事件会被丢弃。

当 **连续 20 次投递** 用尽全部尝试仍然失败后，端点会被自动禁用（状态为 `auto_disabled`），在你重新启用之前不会收到任何内容。期间发生的事件不会补发。当投递开始失败、端点被禁用，以及积压超过六小时时（每天最多一次），团队所有者会收到邮件。

投递是至少一次，且事件不保证顺序。同一个事件可能到达多次，事件到达的顺序也可能与发生的顺序不同：同一封邮件的 `email.delivered` 可能先于 `email.sent` 到达。请让你的处理程序具备幂等性，以 `webhook-id` 为键，并按载荷中的 `created_at`（事件发生的时间）而不是到达顺序来排列一封邮件的事件。有一个例外：原因为 `send_interrupted` 的 `email.failed` 只是一个推测，同一封邮件之后出现的 `email.sent`、`email.delivered` 或其他结果会取代它，即使这些事件的 `created_at` 更早。

```ts
// event：已验证的载荷；webhookId：webhook-id 请求头。
if (await alreadyHandled(webhookId)) return; // 重复投递
const at = new Date(event.created_at);
const known = await db.emailStatus(event.data.email_id); // { status, at, guess } 或 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);
```

## 投递日志

在控制台中打开一个端点，可以看到每一次投递：事件、载荷、你的响应以及每次尝试，保存 30 天。你可以对某次投递点击 **立即重试**，也可以点击 **发送测试事件** 来测试端点。页面还会显示该端点的队列长度，以及最早的投递已等待了多久。

## 限制

| | Free | Starter、Pro、Scale |
| --- | --- | --- |
| 每个团队的 Webhook 端点数 | 1 | 不限 |

超过上限后，`POST /webhooks` 返回 `403 plan_limit_reached`。降级之后，已有的端点继续工作，但不能再添加。让每个端点只订阅它需要的事件：订阅「全部事件」的端点，每导入一位联系人就会收到一个 `contact.created`。
