用途:构建经过验证、幂等的 Ramp Webhook 接收端,在解析前先校验真实性,持久接收后再确认,并把每个事件视为对当前资源状态进行对账的通知。
主要能力:新订阅从 pending_verification 开始,需回传并提交 Ramp 发送的 challenge 才能激活;业务投递带 X-Ramp-Webhook-ID 与 X-Ramp-Signature,后者是对精确原始请求体用订阅密钥计算的 HMAC-SHA256;接收端须在 10 秒内响应,Ramp 对 429、5xx、超时和连接错误最多重试 10 次,采用指数退避与抖动;同一事件 ID 在重试中复用,事件可能乱序到达。
使用方式:只选有文档的事件类型与底层读取 scope,注册 HTTPS 端点并把返回的 webhook 密钥存入批准的密钥管理器;完成 challenge 流程并记录订阅 ID、状态、业务、事件、scope、端点、密钥版本与负责人,且不记录密钥;捕获精确原始字节,用常量时间比较校验签名,校验预期事件与业务,再按稳定事件 ID 去重;在 10 秒内返回 2xx 前先持久入队,异步处理,业务动作需要完整或有序数据时拉取当前资源状态。测试重复、无效签名、未知事件、乱序、429/5xx 重试、密钥轮换、队列失败与定时 API 对账。
适用场景:接收 transactions.ready_to_sync 等事件,校验入队后拉取当前交易状态并创建幂等的 ERP 工作项;轮换订阅密钥并验证无效签名失败、重复事件 ID 不产生重复效果。
限制:需先确认 Ramp 应用、环境、业务实体、受影响数据与工作流、负责人与回滚边界;上线前重读 references/official-docs.md 并核对端点 schema、scope、限制与支持状态;生产访问与业务影响需明确批准前使用合成夹具或 Ramp 沙箱;本地文件工具不授权 Ramp 操作,也不替代负责人批准;未解决的供应商行为、权限或财务状态应视为停止条件。