SuperAPI AI 工具集

webhook-system

通用与其它

查看项目

更新于 10-15 22:19

技能介绍

该技能用于构建生产级出站 Webhook 系统,围绕五个必须各自正确的关注点:订阅管理、投递、签名、失败跟踪与重新投递。任一环节出错都会破坏与消费方的契约。

用途与流程:先做发现(明确触发事件、事件来源、是否有序、投递保证、持久化层与消费方类型),再设计数据模型(webhook_endpoints 与 webhook_deliveries 两张表,含 idempotency_key、scheduled_at、disabled_at 等字段),然后实现签名、投递 worker、熔断、重新投递 API,并处理非显而易见的失败模式。

主要能力:使用 HMAC-SHA256 对每次投递签名,签名含时间戳以防重放,消费方用 timingSafeEqual 校验;支持多密钥轮换。投递 worker 异步执行,4xx(除 429)不重试,5xx 与 429 重试;采用指数退避加抖动(1m、5m、30m、2h、24h)。熔断在失败达阈值后停用端点并通知。重新投递 API 支持单条与批量,插入新行而不修改原始记录。

使用方式:事件发出时仅同步入队,worker 异步投递;提供 /webhooks/deliveries/:id/redeliver 与 /webhooks/endpoints/:id/redeliver 接口。

限制与注意:传输层无法实现 exactly-once,需消费方幂等;投递时重新解析 DNS 并做 SSRF 防护;载荷需版本化;日志需脱敏或设 TTL;worker 需按端点限制并发。具体部署与运行细节暂未提供。