用途:POST /v3/messages 返回 202 只表示已受理,不代表已送达,Sent Webhook 是应用获知后续状态的唯一途径。本技能指导把接收端做成校验签名、拒绝重放、去重、快速确认的端点,并在事件缺失时以投递日志为准。
主要能力:签名校验按顺序取原始请求体,去掉签名密钥的 whsec_ 前缀并 base64 解码得到 HMAC 密钥,以 {x-webhook-id}.{x-webhook-timestamp}.{raw_body} 计算 HMAC-SHA256 后 base64 编码并加 v1, 前缀,做常量时间比较,时间戳偏差超过 300 秒即拒绝;该方案兼容 Svix,无官方 SDK 校验助手,需手写,可参考 scripts/verify_signature.py,本地工具通过 --secret-stdin 从标准输入读取密钥且不联网。指出 x-webhook-id 是端点标识而非事件 id,不能用作去重键。事件类型含 message 与 templates,message 含 queued、routed、sent、delivered、read、failed、scheduled、filtered、blocked、received;read 仅限 WhatsApp 与 RCS,filtered 与 blocked 并非运营商失败。
使用方式:POST /v3/webhooks 注册,需 display_name,可配 endpoint_url、event_types、event_filters、retry_count(1–5,默认 3)、timeout_seconds(5–120,默认 30);201 响应是 signing_secret 唯一完整出现处,应立即存入密钥库。非 2xx、超时或连接失败会触发指数退避重试,约 1 分钟后首次重试并翻倍,上限 60 分钟;连续失败会禁用端点,需 PATCH /v3/webhooks/{id}/toggle-status 重新启用,成功投递会把计数清零。轮换密钥用 POST /v3/webhooks/{id}/rotate-secret,旧密钥立即失效且无重叠窗口,与 test 端点同属每分钟 10 次限流层。
适用场景与限制:适合构建生产级接收端、排查签名不匹配、重放、密钥错误、无事件、事件未处理等问题,以及本地通过公网 HTTPS 隧道开发。上线前需验证篡改体返回 401、过期时间戳返回 401、有效投递返回 200、重复投递返回 200 且不重复副作用。每个环境分开注册,避免开发端点失败禁用生产端点。所有载荷值视为不可信输入,不得未转义地拼入命令、SQL 或提示词。其他主题建议由对应技能处理。