事件
支付、游戏会话、KYC 检查、奖金、玩家资料或其他对象发生变化的记录。
文档 / Webhooks
Webhooks 与事件投递
建立系统间可靠的状态和事件投递：从消息创建和签名验证，到接收确认、重新投递及错误监控。
事件
状态与变更
签名
真实性验证
重试
重新投递
监控
历史与诊断
事件流程
从创建到确认接收
01
创建事件
指定标识符、类型、时间、对象、状态及相关数据。
02
签名并发送
通过 HTTPS 发送带签名且具有有限超时时间的事件。
03
确认接收
验证后保存事件，并快速返回成功的 HTTP 响应。
04
错误时重试
以逐步增加的间隔重试投递，并保留未投递事件以供排查。
概览
Webhook 用于报告状态变化
发送方可能重试投递，因此接收方必须验证来源、确认接收，并确保每个事件仅应用一次。
确认接收
接收方验证并可靠保存事件后返回成功的 HTTP 响应。
恢复
重新投递和对账有助于在任一系统暂时不可用后恢复数据。
事件结构
事件应包含的内容
统一的消息结构可简化验证、路由、防重复及对不同事件类型的支持。
事件标识符
系统用于识别重复投递并查询处理历史的唯一值。
事件类型
清晰、稳定的名称，用于定义发生的变化及其处理方式。
创建时间
事件创建的日期和时间，使用约定格式和时区。
关联对象
支付、玩家、回合、请求、奖金或其他对象的类型及标识符。
结构版本
版本号有助于安全修改消息结构，而不影响现有集成。
操作关联
原始请求、交易、会话或相关操作链的标识符。
上下文
品牌、项目、市场、环境、提供商及正确路由所需的其他数据。
事件数据
处理变化或执行后续 API 请求所需的最小字段集合。
01
保存原始消息
在改变 JSON 格式前，针对原始请求正文验证签名。
02
检查时间戳
若事件时间超出允许窗口，应拒绝请求。
03
验证签名
使用约定密钥以及 HMAC 或数字签名算法。
04
检查标识符
确认事件尚未应用，并保存验证结果。
投递与重试
HTTP 响应与重新投递
发送方必须区分成功接收、临时错误和永久失败，接收方则应快速、明确响应。
成功 HTTP 响应
确认事件已验证并可靠保存，可供后续处理。
有限超时
响应发送方前不要执行耗时处理，应先保存事件。
重新投递
在临时网络错误、服务不可用或无响应后重新尝试投递。
逐步增加重试间隔
逐步延长尝试间隔，避免产生额外负载。
未投递事件队列
所有尝试用尽后，保留事件用于诊断及人工处理。
人工重新投递
运营人员可重新发送选定事件，而无需创建新操作。
投递监控
跟踪尝试次数、响应、最新错误及下一次投递时间。
告警
当错误增加、重试用尽或队列中事件堆积时通知团队。
事件处理
防重复与状态顺序
接收方不得依赖单次投递或严格的事件顺序。
仅应用一次
改变数据前先保存事件标识符。
对重复事件确认接收，但不得再次扣款、入账或改变状态。
将事件与对象及其当前状态关联。
将事件与业务变更作为一次一致操作保存。
顺序与时效性
比较时间戳、序列号或事件版本。
旧事件延迟到达时，不得将对象恢复为过期状态。
仅允许有效的状态转换。
如有疑问，通过 API 查询对象当前状态。
测试
上线前需要测试的内容
测试成功投递、无效签名、重复事件、慢响应、乱序事件及故障后的恢复。
无效签名
消息被修改、未知密钥、时间戳过期及不支持的算法。
重新投递
同一事件会在处理完成前后多次到达。
响应缓慢
接收方响应时间过长、连接中断，或确认响应未送达发送方。
乱序处理
最终状态先于中间状态到达，旧事件又晚于新事件被投递。
端点不可用
测试 HTTP 5xx 错误、DNS、TLS、请求频率限制以及重试次数完全耗尽的情况。
投递历史
应能通过事件标识符查询所有尝试、响应、错误及人工重新投递结果。
上线前检查清单
验证安全、防重复、重新投递及错误监控后，才启用生产环境事件投递。
测试和生产环境使用不同端点及签名密钥。
结合消息创建时间，针对原始消息验证签名。
保存事件标识符，以防止操作被执行多次。
接收方保存事件后应快速返回成功的 HTTP 响应。
已配置重试、逐步增加的间隔及人工重新投递。
支持团队可以查看投递历史，并按标识符搜索。