用途
Postmark Webhooks 用于在邮件发送后，将实时事件数据通过 HTTP POST 推送到你的端点，从而跟踪邮件的投递、退信、打开、点击、垃圾邮件投诉和订阅变更等情况。本技能覆盖出站 Webhook 的六种事件类型；入站邮件 Webhook 运行在独立基础设施上，重试行为不同，请参阅 postmark-inbound。
主要能力
支持六种事件类型：
- Delivery：邮件被收件服务器接受，用于确认投递、更新状态。
- Bounce：邮件被收件服务器拒绝，用于清理列表、通知支持团队。
- SpamComplaint：收件人标记为垃圾邮件，用于从列表移除、调查。
- Open：收件人打开邮件（跟踪像素），用于互动分析。
- Click：收件人点击跟踪链接，用于互动分析、转化跟踪。
- SubscriptionChange：收件人退订，用于更新偏好、合规。
Webhook API 端点包括：列出、获取、创建、更新、删除 Webhook，按需验证端点，以及获取单个 Webhook 的投递统计（滚动 24 小时）。
使用方式
快速开始步骤：
- 通过 API 或 Postmark 控制台（Server → Webhooks）创建 Webhook。
- 设置端点 URL，必须接受 HTTP POST 并返回 200。
- 选择事件触发器。
- 通过验证：创建和编辑时，Postmark 会针对每个启用的事件类型测试端点，每个都必须返回 HTTP 200 才能保存为已验证。
- 处理载荷：解析每种事件类型的 JSON 正文。
- 返回 200：立即确认接收，然后异步处理。
创建 Webhook 可使用 Node.js SDK 或 cURL。示例代码中可配置 Url、MessageStream、Verify、HttpAuth、HttpHeaders 和 Triggers。触发器选项包括：Open 支持 PostFirstOpenOnly；Bounce 和 SpamComplaint 支持 IncludeContent；其他触发器仅支持 Enabled。
端点验证：Verify 字段默认为 true，表示保存前测试每个启用的触发器；设为 false 则跳过测试，Webhook 保持未验证状态且不接收事件，直到后续通过验证。创建或编辑时验证失败会返回 HTTP 422 和错误码 1364，创建时不保存任何内容，编辑时保留原有 Webhook 不变。按需验证使用 POST /webhooks/{Id}/verify，返回 200 仅表示检查已运行，需读取 Success 字段判断结果，Success 可能为 false。响应体报告每个触发器的结果和摘要消息。
如果某个事件类型持续失败，Postmark 会将该事件类型标记为未验证并暂停其投递，直到端点修复并重新验证。此跟踪按事件类型独立，Bounce 失败不会暂停 Delivery 或 Open。
重试与失败处理
重试适用于出站 Webhook。入站邮件 Webhook 使用不同的更长计划，请参阅 postmark-inbound。
可重试的失败：5xx、408 Request Timeout、429 Too Many Requests、网络超时。其他所有 4xx（400、401、403、404、405、410、422）为永久失败，首次尝试即丢弃，不重试。3xx 默认跟随重定向，Postmark 分类最终状态；裸 3xx 会重试而非丢弃。
重试计划：可重试失败最多 9 次重试，约 72 分钟。分两个阶段：标准阶段 3 次重试，间隔 1 分钟、5 分钟、15 分钟，共 21 分钟；退避阶段 6 次重试，间隔 1 分钟、5 分钟、10 分钟、10 分钟、10 分钟、15 分钟，共 51 分钟。第 9 次重试后事件永久丢弃。间隔并非单调递增，退避阶段开始时重置为 1 分钟。同一 9 次重试阶梯适用于所有出站事件类型，不可按 Webhook 或事件类型自定义。每次尝试携带 X-PM-Retries-Remaining 头，首次失败时为 9，在两个阶段中递减。
Webhook 统计
GET /webhooks/{Id}/statistics 返回单个 Webhook 的投递统计，按 ID 查询。没有全量或按流的变体，也没有状态过滤器。窗口固定为滚动 24 小时，v1 中不可过滤。响应包含 WebhookId、Url、Statuses（每个事件类型的验证状态）、TimeRange、Metrics（顶层聚合：TotalRequests、SuccessCount、FailureCount、RetryCount、SuccessRate、SlowCount、VerySlowCount、AverageTerminalResponseTimeMs、AverageRetryResponseTimeMs）和 MetricsByTrigger（按事件类型细分相同指标）。AverageRetryResponseTimeMs 在触发器无重试时为 null。使用 Statuses 发现暂停的事件类型，用每个触发器的 SuccessRate 找出失败者。
Webhook 载荷
所有载荷包含 RecordType、MessageID、MessageStream 和 Metadata（来自原始发送）。使用 RecordType 路由事件。示例代码展示了在 Node.js 中根据 RecordType 分发到不同处理函数。
退信类型包括：HardBounce（代码 1，永久，从所有列表移除）、SoftBounce（代码 4096，临时，Postmark 重试，监控）、Transient（代码 2，临时，重试可能成功）、SpamNotification（代码 512，在收件服务器标记为垃圾邮件）、Blocked（代码 16，被收件服务器阻止）、DMARCPolicy（代码 100000，因 DMARC 策略拒绝）。
幂等性
重试可能重新投递端点已处理的事件，例如处理了事件但响应太慢。处理器必须幂等。基于重试稳定的 X-PM-Webhook-Trace-Id 头去重，头缺失时回退到 MessageID。先返回 200，再处理。
安全
Postmark 不对 Webhook 请求签名，没有 HMAC 签名或签名头可验证。不要编写或信任签名验证逻辑。使用 HTTP Basic Auth（凭据在 Webhook URL 或 HttpAuth 字段中）、IP 白名单和载荷形状校验来保护端点。
退信管理
结合 Bounces API 和 Suppression Management API 与 Webhook 进行全面的退信处理。
常见错误
- 不返回 200：始终返回 HTTP 200，即使处理失败，异步处理。
- 处理缓慢：立即返回 200，然后在后台处理。
- 将 /verify 的 200 视为已验证：200 表示检查已运行，需读取 Success 字段。
- 验证 HMAC 签名：Postmark 不签名 Webhook，没有签名头。
- 无认证：使用 HTTP Basic Auth 或自定义头验证来源。
- 忽略退信类型：HardBounce 与 SoftBounce 处理不同，硬退信需永久抑制。
- 不处理部分数据：某些字段可能缺失，访问前检查存在性。
- 非幂等处理器：重试可能重新投递已处理事件，基于 X-PM-Webhook-Trace-Id 去重。
- 期望 4xx 被重试：仅 5xx、408、429 和网络超时重试，其他 4xx 永久丢弃。
- 假设 X-PM-Retries-Remaining: 9 是 bug：9 是正确起始值。
- 缺少 MessageStream 过滤：创建 Webhook 时指定 MessageStream 避免跨流事件。
- 不跟踪元数据：发送时包含 Metadata 以关联 Webhook 事件与记录。
注意事项
Webhook 按消息流配置，出站和广播需分别创建。始终立即返回 HTTP 200，异步处理数据。创建和编辑时测试每个启用的事件类型，每个必须返回 200 才能保存为已验证。验证失败返回 422 和错误码 1364。出站重试最多 9 次约 72 分钟，两个阶段，仅 5xx、408、429 和网络超时重试。持久失败仅暂停该事件类型。处理器必须幂等。使用 MessageID 关联事件与已发送邮件。所有载荷包含原始发送的 Metadata。打开跟踪需要 HTML 中的跟踪像素，纯文本邮件无效。点击跟踪需要在发送邮件时启用 TrackLinks。退信 Webhook 对退信和阻止触发，检查 Type 字段区分。垃圾邮件投诉、退订和手动停用有各自事件类型（非 Bounce）。个人打开/点击数据存储 45 天，聚合统计无限期存储。