使用控制台Webhooks
在服务端接收 Webhook
Webhooks: 在服务端接收 Webhook
请求头和鉴权
Webhook 请求会携带用于鉴权的 Bearer Token。你的服务端应：
- 从请求头读取 Authorization 信息。
- 提取 Bearer Token。
- 与服务端安全存储的 Token 比较。
- 校验失败时拒绝请求。
- 校验成功后再解析和处理 Payload。
不要只根据来源 IP 判断回调是否合法，也不要把 Token 记录到普通业务日志。
Payload
Payload 的完整字段和版本以 GEELAB 当前 Webhook Payload Reference 为准。你的服务端至少应能够识别：
- 事件类型。
- Request ID。
- 应用和接入端信息。
- 事件时间。
- Device ID 或识别信息。
- 风险信号（如果本次事件命中）。
收到 Request ID 后，可以根据业务需要调用服务端 API 获取更完整的事件信息。不要仅依赖客户端上报的内容做高风险决策。
事件类型
如果订阅“全部识别事件”，服务端应能够处理正常事件和高风险事件。如果订阅“仅高风险事件”，服务端仍应根据 Payload 中的事件类型和风险信号进行校验，不要假设每条回调都包含同样的字段。
版本兼容
处理 Payload 时建议：
- 使用事件类型和字段名判断，而不是依赖字段顺序。
- 对新增字段保持兼容，忽略暂时不需要的未知字段。
- 对缺失的可选字段进行容错。
- 保存 Payload 版本或请求头中的版本信息（如果提供）。
- 关注 GEELAB 的更新说明，在升级前进行测试。
不要把完整 Payload 结构硬编码成无法演进的严格字符串匹配。
投递语义
当前版本的 Webhook 采用异步、单次投递模型：平台对每条事件只发起一次 HTTP 请求，不会因为目标服务返回错误或超时而自动重试。你的接收服务应自行做好幂等处理，并通过投递日志确认最终结果。
不同事件可能并行发送，因此不保证严格按事件发生时间到达。处理有先后依赖的业务时，请结合事件时间、业务状态和 Request ID 判断是否可以执行，不要仅依赖到达顺序。
图示：Webhook 请求与事件信息