Telm 可以把审核事件实时推送到你的服务器。你注册一个端点，选择要接收哪些事件，Telm 会为每个事件发送一个签名的 POST。每次投递都携带一个你用端点密钥验证的 HMAC-SHA256 签名。失败的投递会按计划重试；永久无法到达的端点会被自动禁用。
1事件信封
每个 webhook 都是一个 HTTP POST，其 JSON 主体包在一个通用的 信封 中。信封有一个 id（用于去重的唯一投递标识符）、一个 type（事件名）、一个 created_at 时间戳、该事件所属的 group_id，以及一个 data 对象，其结构取决于事件类型。
对于真实事件，id 是确定性的，因此如果同一事件被投递两次——例如在一次重试之后——你会两次收到相同的 id。用 X-Telm-Delivery 头（它镜像这个 id）作为幂等键，让你的处理程序对每个事件只处理一次。
- 信封字段：id、type、created_at、group_id、data。
- type 是下方目录中的其中一个事件名。
- data 携带特定于事件的字段。
- 用 id（和 X-Telm-Delivery 头）对重试去重。
2事件目录
你把一个端点订阅到目录的任意子集。spam.detected 在引擎把一条消息标记为垃圾时触发。message.suspicious 在监控模式下触发，此时引擎本会采取行动但只对消息进行了影子评分。成员事件涵盖人员进入、离开和被惩罚。
ping 事件很特殊：它不是可订阅目录的一部分，只在你为一个端点触发一次测试投递时才发送，因此你可以端到端地确认你的接收器和签名检查有效。
- spam.detected——一条消息被分类为垃圾。
- message.suspicious——一次影子（监控模式）检测。
- user.banned、user.kicked、user.muted——一个审核动作被施加。
- user.joined、user.left——一个成员进入或离开了群组。
- ping——一个手动测试事件，绝不由真实活动触发。
3每个事件的载荷字段
对于 spam.detected 和 message.suspicious，data 对象携带 message_id、user_id、username、消息文本（对非常长的消息会被截断）、所采取的 action、一个 category、一个 reason、检测到的语言，以及一个置信度评分。message.suspicious 额外携带影子评分。
对于成员事件（user.joined、user.left、user.banned、user.kicked、user.muted），data 对象携带 user_id、username、first_name、一个可选的 message_id，以及在适用处的一个 reason。一个底层事件可以产生不止一个 webhook——一条触发封禁的垃圾消息会同时作为 spam.detected 和 user.banned 被投递。
- 垃圾事件：message_id、user_id、username、text、action、category、reason、language、confidence（对 message.suspicious 另加 score）。
- 成员事件：user_id、username、first_name、message_id、reason。
- 单起事件可能发出多个事件；用 user_id 和 group_id 将它们关联。
4验证 HMAC 签名
每次投递都被签名，因此你可以确定它确实来自 Telm 且未被篡改。你会在创建端点时得到一个 端点密钥（它以 whsec_ 开头），一次。把它存起来，用它来验证每个进入的请求。
要验证，取 X-Telm-Timestamp 头的值，追加一个点，然后追加确切的原始请求主体，并用你的端点密钥作为密钥对该字符串计算一个 HMAC-SHA256。将结果进行十六进制编码并加上前缀 v1=——它必须等于 X-Telm-Signature 头。用恒定时间比较进行比对，并且如果时间戳早于几分钟（五分钟是一个好的截止点）就拒绝该请求，以阻止重放。
- X-Telm-Event——事件类型。
- X-Telm-Delivery——投递 id（幂等键）。
- X-Telm-Timestamp——unix 秒，经签名以防止重放。
- X-Telm-Signature——v1= 加上时间戳、一个点和原始主体的十六进制 HMAC-SHA256。
5投递、重试与自动禁用
只有当你的端点以 2xx 状态响应时，一次投递才算成功。任何其他情况——一个非 2xx 码、一次超时或一个连接错误——都被视为失败，并按固定计划重试：立即，然后在 1 分钟、5 分钟、30 分钟、2 小时和 6 小时之后，共六次尝试，跨越大约八个半小时，之后该投递被作为失败关闭。
如果一个端点持续失败——至少连续二十次失败且三天内没有一次成功投递——Telm 会自动禁用它，使其停止向一个失效的 URL 发送。一旦你的接收器再次健康，你可以从仪表盘重新启用它。
- 成功 = HTTP 2xx。快速响应（约十秒内）并异步执行繁重的工作。
- 重试计划：立即、+1m、+5m、+30m、+2h、+6h（六次尝试）。
- 在 72 小时内连续 20 次失败且无一成功后自动禁用。
- 注册 webhook 需要 Pro 套餐或更高。