跳到内容
Esc
↑↓导航↵打开⌘J预览
本页内容

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。

这个页面有帮助吗?