开发者 · Webhooks
为出金生命周期提供 HMAC 签名的 Webhooks。
当你的产品需要异步获取生命周期状态时，注册 Webhook 端点并校验每一次投递。签名将时间戳与精确的原始消息体绑定，让你能拒绝被篡改或被重放的载荷。
01
生命周期事件
| 事件 | 含义 |
|---|---|
| deposit.created | 一笔卖方存款已在 Base 上创建 |
| deposit.partially_filled | 一笔存款部分成交 |
| deposit.filled | 一笔存款已全部成交 |
| deposit.closed | 卖方关闭存款或提取了剩余余额 |
| otc.taken | 一笔私有 OTC 存款被已批准的买方成交 |
02
校验每一次投递
- 1读取格式为 t=<unix>,v1=<hex> 的 X-Usdctofiat-Signature 请求头。
- 2使用原始、未解析的消息体，将签名载荷构造为字符串 timestamp.rawBody。
- 3用你的端点密钥在该载荷上计算 HMAC-SHA256。
- 4在信任该事件之前，以常量时间与 v1 十六进制值比较。
- 5可选：拒绝那些时间戳早于你所选时间窗的投递。
03
重放防护由你决定
起步模板仓库中的参考接收端会将早于 5 分钟的时间戳视为过期，以防范重放。该时间窗由你的校验器执行，而非发送方，因此你可以根据自己的延迟和重试容忍度收紧或放宽它。
由于签名覆盖的是 timestamp.rawBody，请仅在 HMAC 校验通过后再解析 JSON。校验解析后的对象而非原始字节，是最常见导致签名校验微妙出错的方式。
04
注册与运营
- 用你的 Peerlytics API 密钥注册端点；一个密钥即可对 offramp 与 Peerlytics 接口完成鉴权。
- 连续多次投递失败的端点可被禁用，直到你修复它们为止。
- 将起步模板仓库的接收端作为一个已知良好的 HMAC 校验参考。
- 将 Webhooks 视为状态提示；当事关重大时，用 deposits() 与链上真实状态对账。
Keep exploring
Common questions
USDCtoFiat 的 Webhooks 如何签名？
每次投递都携带 X-Usdctofiat-Signature: t=<unix>,v1=<hex>，这是在字符串 timestamp.rawBody 上计算的 HMAC-SHA256。在信任该事件前，用你的端点密钥在原始消息体上重新计算 HMAC，并以常量时间比较。
我如何防止被重放的 Webhooks？
拒绝那些签名时间戳早于你所选时间窗的投递。参考接收端使用 5 分钟。发送方不强制任何时间窗，因此这是你校验器的职责。
Webhooks 需要 API 密钥吗？
需要。创建存款无需许可，但注册 Webhook 端点要用 Peerlytics API 密钥。同一个密钥也为 Peerlytics API 鉴权。