Webhook 参考
为希望 PulseCargo 将事件推送到自有系统的租户提供的出站 webhook 投递 — 计划导出、SIEM 事件出口、供应商付款事件。
可用的 Webhook 目标
今天提供三个出站 webhook 接口：
计划导出 Webhook
触发条件。计划导出作业完成时（任何模块的 CSV / XLSX / JSON）。
使用场景。将导出负载落地到您的数据湖、S3 存储桶或下游管道，无需轮询。
套餐。Professional 及以上。
SIEM 事件 Webhook
触发条件。安全事件（登录失败、MFA 挑战、管理员操作、可疑访问模式、集成审计异常）。
使用场景。转发到您的 SIEM（CrowdStrike、Microsoft Sentinel、Splunk、Datadog、Cloudflare，或通用 webhook 到任何自定义目标）。
套餐。Enterprise+ 默认提供安全事件出口；Enterprise 可选启用。
PayCargo 供应商付款 Webhook
触发条件。供应商付款状态变更（已提交、已接受、已结算、已拒绝、已退款）。
使用场景。与您的 AP 系统对账；触发下游通知。
套餐。Professional 及以上。注意：PayCargo 实时 API 需要合作伙伴凭证；在正式集成上线之前，webhook 负载通过存根客户端流式传输。
通用信封
每个 webhook 投递都使用一个通用的 JSON 信封：
{
"event_id": "evt_01HZQX...",
"event_type": "scheduled_export.completed",
"tenant_id": "acme-logistics",
"timestamp": "2026-05-09T14:32:08Z",
"delivery_attempt": 1,
"data": { ... event-specific payload ... }
}event_id 在每个逻辑事件中唯一 — 请基于此 ID 进行幂等消费，因为重试会以相同的 ID 投递，但 delivery_attempt 会递增。
签名验证
每个 webhook 投递都包含一个 X-PulseCargo-Signature 头，其中包含使用您租户的 webhook 签名密钥对请求体计算得出的 HMAC-SHA256 签名。
伪代码验证方式：
signature = HMAC-SHA256(your_signing_secret, request.body)
expected = request.headers["X-PulseCargo-Signature"]
constant_time_equal(signature, expected) // 必须使用常量时间比较拒绝任何签名不匹配的请求。签名密钥可轮换；轮换会通过管理界面提前 30 天通知。
重试策略
如果您的端点返回非 2xx 状态码（或在 10 秒内未响应），PulseCargo 会以指数退避方式重试：
- 第 1 次尝试 — 立即
- 第 2 次尝试 — 1 分钟后
- 第 3 次尝试 — 5 分钟后
- 第 4 次尝试 — 30 分钟后
- 第 5 次尝试 — 2 小时后
- 第 6 次尝试 — 12 小时后
- 第 7 次尝试（最终）— 24 小时后
第七次尝试失败后，事件被标记为永久失败，并显示在租户的 webhook 健康仪表板中。原始 event_id 会被保留，以便手动重发（在您修复接收端点后）能够干净地对账。
接收方要求
- 快速响应。在 10 秒内返回 2xx。如需要，异步处理负载。
- 幂等性。基于
event_id。首次成功处理后，将重复投递视为无操作。 - 验证签名。拒绝没有有效签名的请求。
- 使用 HTTPS。生产环境的 webhook 不允许使用 HTTP 端点。
- 允许我们的 IP 范围。如果您的端点有防火墙保护，请允许 PulseCargo 的出站 IP 范围（在管理界面提供）访问您。
健康监控
租户管理员可以在 Admin → Integrations → Webhooks 下查看 webhook 投递健康状况：每个目标的成功率、最近一次成功投递、当前正在重试的事件、带有重放按钮的永久失败事件。
永久失败的事件保留 90 天供重放；更早的失败事件会被清除。
安全与审计
每次出站 webhook 投递都会记录在 OutboundApiTraffic 中，包含时间戳、目标 URL、响应状态和投递尝试次数。租户管理员可以查询日志以获取合规证据。
签名密钥轮换、目标 URL 更改和 webhook 开关切换都会被审计记录。SOC 2 证据收集。