Webhook 在审核事件发生那一刻把它们推送到你的 URL——垃圾检测、封禁、踢出、禁言，以及成员加入或离开。每次投递都用 HMAC-SHA256 签名（对一个 whsec_ 密钥验证）、携带一个稳定的 delivery id 用于去重，如果你的服务器不可达则按计划重试。Webhook 是 Pro 套餐及以上的一部分。
1Webhook 做什么
你不用轮询 API，而是注册一个 URL，每当你群组里发生某事时 Telm 就向它发送一个签名的 HTTP POST。这就是你实时地把审核事件送进你自己系统——一个仪表盘、一个数据仓库、一个告警渠道——的方式。
你通过 API 管理 webhook 端点：注册一个 URL、选择要订阅哪些事件、可选地把它们限定到特定群组、发送一次测试 ping，并读取最近的投递日志。
2为什么推送胜过轮询
你可以定时调用日志端点去找新事件，但那会增加延迟、花掉配额，还可能错过某事发生的确切时刻。Webhook 翻转了这个模型：Telm 在一个事件触发的瞬间告诉你，因此你的系统在几秒内作出反应。
典型用途包括把封禁镜像到你自己的管理工具、在检测到突袭时向一个团队渠道告警、把检测流式传入分析，或在一个成员加入或离开时触发一个工作流。
- 实时：你在一个事件发生时就得知它，而不是在你下一次轮询时。
- 高效：没有反复的读取来啃食你的每日配额。
- 完整：投递会重试，因此你这边一次短暂的中断不会丢失事件。
3你可以订阅的事件
有七种可订阅的事件类型，涵盖垃圾裁决、惩罚和成员变更。一条被审核的消息可以产生不止一个事件——一条以封禁告终的垃圾消息会同时发出 spam.detected 和 user.banned。
- spam.detected——引擎把一条消息标记为垃圾。
- message.suspicious——一次带分数的影子（监控模式）检测。
- user.banned——一个成员被封禁。
- user.kicked——一个成员被移除。
- user.muted——一个成员被禁言。
- user.joined——一个成员加入了群组。
- user.left——一个成员离开了群组。
4载荷信封
每次投递都是一个 JSON 信封，带一小组稳定的顶层字段，内部有一个特定于事件的 data 对象。你可以按 type 和 time 路由，而在需要之前不解析细节。
- id——一个唯一的 delivery id；同一事件的重新投递复用同一个 id，这就是你去重的方式。
- type——事件类型，上述七个之一。
- created_at——事件触发的时间，采用 RFC3339 UTC。
- group_id——事件所属的群组（在适用时）。
- data——一个特定于事件的对象：垃圾事件的消息和裁决细节，成员事件的成员细节。
5验证投递确实来自 Telm
每次投递都经过签名，因此你的服务器能确认请求确实来自 Telm 且在传输中未被篡改。在你信任载荷之前校验签名，并拒绝任何不匹配的东西。
签名是时间戳和原始请求主体的 HMAC-SHA256，用你的端点签名密钥作为密钥。要验证，在时间戳标头和你收到的确切字节上重新计算 HMAC，并把它与签名标头比较。
- X-Telm-Signature——签名，格式为 v1 后跟时间戳拼接主体的十六进制 HMAC-SHA256。
- X-Telm-Timestamp——被签名的 unix 秒时间戳，因此你可以拒绝陈旧或重放的投递。
- X-Telm-Event——事件类型，X-Telm-Delivery——用于去重的 delivery id。
- 签名密钥在你创建端点时显示一次，以 whsec_ 开头。安全地存储它；它是唯一能证明一次投递为真的东西。
6可靠、去重的投递
投递是至少一次：Telm 确保一个事件到达你，这意味着同一个事件偶尔会到达两次。因为每次重新投递复用同一个 delivery id，你通过存储已处理的 id 并跳过重复来去重。
如果你的端点不可达或返回一个错误，投递会按一个固定的计划重试——大约在一分钟、五分钟、三十分钟、两小时和六小时后，在约八个半小时内最多六次尝试。一个持续失败的端点会被自动禁用以保护双方，且所有者会被通知。
- 用一个 2xx 状态快速响应；在确认之后异步地做繁重的工作。
- 按 delivery id 去重——永远不要按载荷内容去重。
- 一个在 72 小时窗口内连续失败约二十次而无一成功的端点会被自动禁用；在你的服务器健康后重新启用它。
7管理端点并读取日志
你通过 API 注册、编辑和移除 webhook 端点。当你创建一个时，你恰好一次地收到签名密钥、选择要订阅的事件，并可选地把它限定到特定群组。一次测试调用发送一个签名的 ping，因此你可以在真实流量开始前确认你的校验有效。
每个端点保留一份投递日志，你可以回读它，看看发送了什么、何时发送以及是否成功——这对调试一个接收器很方便，无需等待下一个实时事件。
- 创建一个端点并立即复制 whsec_ 密钥。
- 发送一个测试 ping，端到端地校验你的签名检查。
- 把一个端点限定到一个群组，或让它对你管理的所有群组开放。
- 读取投递日志以检查最近的尝试及其结果。
8最佳实践与常见错误
一个稳健的接收器遵循几条规则，避免最常见的问题。
- 在原始主体字节上校验签名——先解析为 JSON 再重新序列化可能改变字节并破坏检查。
- 快速返回 2xx，稍后处理；一个缓慢的处理器会导致超时和不必要的重试。
- 让处理具有幂等性，这样一个重新投递的事件不会被重复计数。
- 在一个公开可达的 URL 上使用 HTTPS；Telm 会屏蔽内部和私有地址，且不跟随重定向。
- 让 whsec_ 密钥远离日志和客户端代码。