Webhooks

验证每一个投递事件

Postline 会对每个 webhook 进行签名并限制重试次数。接收方必须校验时效性、对事件 ID 去重，并容忍乱序投递。

2026年7月24日更新

事件

每个端点可订阅以下 1–20 种事件类型：

email.accepted
email.queued
email.sent
email.delivered
email.deferred
email.bounced
email.complained
email.opened
email.clicked
email.received
email.suppressed
domain.verified
domain.failed

签名输入

HMAC-SHA256(secret, timestamp + "\0" + event_id + "\0" + body)

Postline-Timestamp: 1784743200
Postline-Event-Id: evt_…
Postline-Signature: v1=…

请求与负载

POST https://example.com/hooks/postline
Content-Type: application/json
Postline-Event-Id: evt_3f2a9c…
Postline-Timestamp: 1784743200
Postline-Signature: v1=5d41402abc4b2a76…

{
  "id": "evt_3f2a9c…",
  "type": "email.delivered",
  "created_at": "2026-11-05T12:00:00Z",
  "data": {
    "email_id": "msg_01J…",
    "recipient": "user@example.net",
    "provider": "gmail",
    "smtp_response": "250 2.0.0 OK"
  }
}

接收方要求

基于原始请求体（raw body）的确切内容计算签名。
以恒定时间（constant time）方式比较签名。
拒绝超出允许时间窗口的 timestamp。
保存 event_id，并确保每个事件只处理一次。
不要假定事件按生命周期顺序到达。

出站控制

创建端点要求使用 HTTPS。私有地址、环回地址（loopback）、link-local 地址、metadata 地址、携带凭据的地址以及内部目标均会被阻止，并在拨号（dial）时重新解析。系统不会跟随重定向。投递采用有限的超时时间与重试次数。

超时与重试

任何 2xx 响应即确认事件。超时（15 秒）、网络错误或其他状态均视为失败。Postline 最多尝试 6 次：首次投递，以及在 1 分钟、5 分钟、30 分钟、2 小时和 8 小时后重试。每次尝试都会记录在投递日志中，任何投递都可以通过 API 或控制台手动重放。