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

Webhook

帶有簽章的事件會推送到你的端點,並提供重試機制與送達記錄。

每當有事情發生,Webhook 就會對你的端點發出一次 HTTP POST:Email 已送達、聯絡人退訂、收到信件等。在控制台的 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 事件

事件 觸發時機
email.scheduled Email 已被接受,且 scheduled_at 在未來。
email.sent Email 已交給郵件服務。
email.delivered 收件者的伺服器已接受。
email.delivery_delayed 正在重試寄送(信箱已滿、灰名單機制)。
email.bounced Email 被退信。data.bounce.type 為 Permanent(硬退信:該位址也會被抑制)、Transient 或 Undetermined(不會被抑制)。
email.complained 收件者標記為垃圾郵件。該位址也會被抑制。
email.failed Email 永遠不會寄出。data.failed.reason 會說明原因。
email.suppressed Email 在寄出前被攔下。data.suppressed.reason 會說明原因。
email.opened 有人開啟了信件(需要在網域上開啟開信追蹤)。
email.clicked 有人點擊了追蹤連結(需要開啟點擊追蹤)。
email.prefetched 由機器而不是真人載入了追蹤像素或跟進連結(隱私代理、資安掃描器)。需主動訂閱,見下方。
email.received 有訊息送達你的其中一個收信網域。data.email_id 可用 GET /emails/receiving/{id} 讀取。

email.prefetched 與每個 inbox.* 事件一樣需主動訂閱:端點只有在明確指定這個事件時才會收到,「所有事件」不包含它。

帳號事件

這些事件不帶 Email。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。Email 與草稿物件不會帶有內文:請用 API 取得。

要把端點限定在某些收件匣,請傳送 inbox_ids(最多 100 個你團隊的收件匣;null 代表所有收件匣,空清單代表都不接收)。在控制台中對應的是僅限這些收件匣。

Payload 內容

每個 Email 事件都帶有 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 Email 寄出時,寄件網域尚未驗證。
domain_deleted Email 在等待期間,寄件網域被刪除了。
held_for_review_expired Email 因安全檢查被擱置,7 天內沒有被放行。
team_suspended 團隊被停權,且在 Email 被擱置後的 7 天內沒有恢復。
broadcasts_paused 團隊的群發被暫停,且在 Email 被擱置後的 7 天內沒有恢復。
ses_tenant_paused SES 暫停了團隊的寄送,且 7 天內沒有解除暫停。
body_missing、body_unreadable 儲存的內容遺失或無法讀取,例如 Email 仍在擱置時,它的內容已超過保存期限。
message_rejected 郵件服務拒絕了這封訊息,例如因為它帶有病毒。
retries_exhausted 每次寄送嘗試都因暫時性錯誤而失敗。
send_interrupted 寄送在確認之前被中斷,所以 Email 可能已寄出,也可能沒有。不會再重試。
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 收件者已退出該 Email 的訂閱主題。
contact_missing、contact_recipient_mismatch Email 寄出前,聯絡人已被刪除,或它的位址已經變更。
broadcast_missing、topic_missing Email 寄出前,群發或訂閱主題已被刪除。
ineligible Email 不再符合寄送資格的其他任何原因。

如果只有部分收件者被排除,Email 仍會寄給其餘的收件者,也不會觸發 email.suppressed。取消群發時,被它攔下的 Email 不會觸發任何事件。

驗證簽章

推送內容遵循 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 的 email.delivered 可能比 email.sent 更早到。請讓你的處理程式具備冪等性,以 webhook-id 作為索引,並依 payload 的 created_at(事件發生的時間)而不是抵達順序來排列一封 Email 的事件。有一個例外:原因為 send_interrupted 的 email.failed 只是推測,同一封 Email 的 email.sent、email.delivered 或其他結果會取代它,即使它們的 created_at 更早。

// event:已驗證的 payload;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);

送達記錄

在控制台打開端點,就能看到每一筆推送:事件、payload、你的回應與每次嘗試,保存 30 天。你可以對推送按立即重試,也可以按傳送測試事件來測試端點。頁面也會顯示端點的佇列大小,以及最舊的推送已經等待多久。

限制

Free Starter、Pro、Scale
每個團隊的 Webhook 端點數 1 無限制

超過限制後,POST /webhooks 會回傳 403 plan_limit_reached。降級後,既有端點仍會繼續運作,但無法再新增。每個端點只訂閱它需要的事件:訂閱「所有事件」的端點,每匯入一位聯絡人就會收到一次 contact.created。

这个页面有帮助吗?