用途:构建向客户端点可靠、安全、可观测地发送事件的外部 Webhook 平台。消费 Webhook 由 idempotent-financial-workflows 覆盖,签名公式与事件模式模板见 REFERENCE.md。
主要能力: 签名:HMAC-SHA256(secret, "v1:" + timestamp + ":" + raw_body),头为 X-Webhook-Signature: t=<unix_ts>,v1=<hex_digest>;签名含时间戳防重放;轮换期间双密钥验证(新旧同时接受 24 小时);可选 Ed25519 公钥验证。 投递与重试:超时内任意 2xx 为成功(建议 30 秒)。4xx(410 除外)、5xx、超时、网络错误触发重试。退避加抖动:30 秒→5 分→30 分→2 小时→8 小时→24 小时。达上限后进入死信队列加仪表盘,可选告警。收到 410 自动禁用端点;2xx 永不重试。 健康与熔断:按最近 100 次投递的滑动窗口统计成功失败比,超阈值(如 1 小时内失败率大于 50%)则禁用并通知客户,需显式重新启用;重启用时回放死信事件(有界、可配置窗口)。 顺序与幂等:至少一次投递,载荷含 idempotency_key,客户须去重;按资源 ID 分队列,跨资源顺序不保证(需文档说明);每资源单调序列号便于检测缺口。 事件模式:字段 id、type(如 invoice.paid)、created_at(ISO 8601 UTC)、api_version、idempotency_key、data。破坏性变更发布新事件类型,禁止修改已有模式;发布 AsyncAPI/OpenAPI 目录。 扇出:事件→内部总线(Kafka、SQS、Postgres LISTEN/NOTIFY)→每订阅投递 worker;不得从原始处理器同步投递。Outbox:事件与状态变更同事务写入,由中继发布到总线。 客户控制:注册端点 URL、选择订阅事件类型;投递日志含请求与响应正文(保留 72 小时);可手动重放;注册时测试 ping;暂停恢复不丢队列事件。
使用方式:按上述签名公式、重试退避序列与模式字段实现;测试分单元(HMAC 签名验证、退避计算)、集成(隧道如 ngrok、Hookdeck,发测试事件并断言签名通过)、失败(500 触发重试,410 禁用端点)、重放(禁用、发事件、重启用,断言遗漏事件有序投递)。
限制与护栏:保留期外不得记录原始正文(PII 风险);禁止同步投递(延迟级联);不得跨事件类型复用幂等键;需明确记录重试与顺序保证。定价、平台与具体实现细节暂未提供。