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。