Webhook
向你的端点发送带签名的事件通知,支持重试,并提供投递日志。
每当有事情发生时,Webhook 都会向你的端点发送一个 HTTP POST 请求:邮件已送达、联系人退订、收到新邮件等。在控制台的 Webhook 中添加端点,或使用 POST /webhooks,并为每个端点选择要接收的事件。SDK 用 verifyWebhook(Node.js)和 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"]
}'
响应中带有 signing_secret(whsec_...)。GET /webhooks/{id} 会再次返回它,列表中的各行从不包含它。
事件
邮件事件
| 事件 | 触发时机 |
|---|---|
email.scheduled |
邮件已被接受,且 scheduled_at 在未来。 |
email.sent |
邮件已交给邮件服务。 |
email.delivered |
收件人的服务器已接受。 |
email.delivery_delayed |
正在重试投递(邮箱已满、灰名单)。 |
email.bounced |
邮件被退信。data.bounce.type 为 Permanent(硬退信:该地址也会被 抑制)、Transient 或 Undetermined(不会被抑制)。 |
email.complained |
收件人把它标记为垃圾邮件。该地址也会被抑制。 |
email.failed |
邮件永远不会被发送。data.failed.reason 说明原因。 |
email.suppressed |
邮件在发送前被拦截。data.suppressed.reason 说明原因。 |
email.opened |
有人打开了邮件(需要在 域名 上开启打开追踪)。 |
email.clicked |
有人点击了被追踪的链接(需要开启点击追踪)。 |
email.prefetched |
是机器而不是真人加载了追踪像素或访问了链接(隐私代理、安全扫描器)。需主动订阅,见下文。 |
email.received |
有邮件到达你的某个 收信域名。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 的含义参见 退订。
收件箱事件
收件箱 会发送 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。
{
"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 |
其他任何使发送中止的错误。 |
{
"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 方案。每个请求都带有:
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}。
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 显示窗口何时结束。
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 更早。
// 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。