---
title: Webhook
description: 帶有簽章的事件會推送到你的端點，並提供重試機制與送達記錄。
seo:
  title: Email Webhook
ai:
  exclude: true
---

每當有事情發生，Webhook 就會對你的端點發出一次 HTTP `POST`：Email 已送達、聯絡人退訂、收到信件等。在控制台的 **Webhook** 新增端點，或使用 `POST /webhooks`，並選擇每個端點要接收哪些事件。[SDK](/docs/zh-hant/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 事件

| 事件 | 觸發時機 |
| --- | --- |
| `email.scheduled` | Email 已被接受，且 `scheduled_at` 在未來。 |
| `email.sent` | Email 已交給郵件服務。 |
| `email.delivered` | 收件者的伺服器已接受。 |
| `email.delivery_delayed` | 正在重試寄送（信箱已滿、灰名單機制）。 |
| `email.bounced` | Email 被退信。`data.bounce.type` 為 `Permanent`（硬退信：該位址也會被[抑制](/docs/zh-hant/concepts/suppressions)）、`Transient` 或 `Undetermined`（不會被抑制）。 |
| `email.complained` | 收件者標記為垃圾郵件。該位址也會被抑制。 |
| `email.failed` | Email 永遠不會寄出。`data.failed.reason` 會說明原因。 |
| `email.suppressed` | Email 在寄出前被攔下。`data.suppressed.reason` 會說明原因。 |
| `email.opened` | 有人開啟了信件（需要在[網域](/docs/zh-hant/concepts/domains)上開啟開信追蹤）。 |
| `email.clicked` | 有人點擊了追蹤連結（需要開啟點擊追蹤）。 |
| `email.prefetched` | 由機器而不是真人載入了追蹤像素或跟進連結（隱私代理、資安掃描器）。需主動訂閱，見下方。 |
| `email.received` | 有訊息送達你的其中一個[收信網域](/docs/zh-hant/receiving)。`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` 的意義請見[退訂](/docs/zh-hant/concepts/unsubscribes)。

### 收件匣事件

[收件匣](/docs/zh-hant/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`。Email 與草稿物件不會帶有內文：請用 API 取得。

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

### Payload 內容

每個 Email 事件都帶有 `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` | 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` | 其他讓寄送停止的錯誤。 |

```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` | 收件者已退出該 Email 的訂閱主題。 |
| `contact_missing`、`contact_recipient_mismatch` | Email 寄出前，聯絡人已被刪除，或它的位址已經變更。 |
| `broadcast_missing`、`topic_missing` | Email 寄出前，群發或訂閱主題已被刪除。 |
| `ineligible` | Email 不再符合寄送資格的其他任何原因。 |

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

## 驗證簽章

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

```ts
// 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`。
