Developers · Webhooks
オフランプのライフサイクルのためのHMAC署名付きWebhook。
あなたのプロダクトが非同期のライフサイクル状態を必要とするとき、Webhookエンドポイントを登録し、各配信を検証してください。署名はタイムスタンプを生のボディそのものに結び付けるため、改ざんやリプレイされたペイロードを拒否できます。
01
ライフサイクルイベント
| イベント | 意味 |
|---|---|
| deposit.created | 売り手の入金がBase上で作成された |
| deposit.partially_filled | 入金の一部が約定した |
| deposit.filled | 入金が完全に約定した |
| deposit.closed | 売り手が残高をクローズまたは引き出した |
| otc.taken | プライベートなOTC入金が承認済みの買い手に約定された |
02
すべての配信を検証する
- 1X-Usdctofiat-Signature ヘッダーを t=<unix>,v1=<hex> の形式で読み取る。
- 2生の未パースのボディを使い、署名対象のペイロードを timestamp.rawBody という文字列として組み立てる。
- 3そのペイロードに対し、エンドポイントのシークレットでHMAC-SHA256を計算する。
- 4イベントを信頼する前に、v1 のhex値と定数時間で比較する。
- 5任意で、タイムスタンプが選択したウィンドウより古い配信を拒否する。
03
リプレイ保護はあなた次第
スターターリポジトリのリファレンスレシーバーは、リプレイを防ぐため5分より古いタイムスタンプを期限切れとして扱います。このウィンドウは送信側ではなくあなたの検証側で適用されるため、レイテンシや再試行の許容度に合わせて狭めたり広げたりできます。
署名は timestamp.rawBody をカバーするため、JSONのパースはHMACチェックが通った後にのみ行ってください。生のバイト列ではなくパース済みのオブジェクトを検証することは、署名検証を微妙に間違える最も一般的な原因です。
04
登録して運用する
- Peerlytics APIキーでエンドポイントを登録します。1つのキーでオフランプとPeerlyticsのサーフェスの両方を認証します。
- 連続した配信失敗を繰り返すエンドポイントは、修正するまで無効化できます。
- スターターリポジトリのレシーバーを、検証済みのHMAC検証リファレンスとして使ってください。
- Webhookは状態のヒントとして扱い、重要な場面では deposits() でオンチェーンの真実と照合してください。
Keep exploring
Common questions
USDCtoFiat のWebhookはどのように署名されますか？
各配信は X-Usdctofiat-Signature: t=<unix>,v1=<hex> を伴い、これは timestamp.rawBody という文字列に対するHMAC-SHA256です。エンドポイントのシークレットで生のボディに対してHMACを再計算し、イベントを信頼する前に定数時間で比較してください。
リプレイされたWebhookをどう防げばよいですか？
署名されたタイムスタンプが、あなたが選択したウィンドウより古い配信を拒否してください。リファレンスレシーバーは5分を使います。送信側はウィンドウを強制しないため、これはあなたの検証側の責任です。
WebhookにAPIキーは必要ですか？
はい。入金の作成はパーミッションレスですが、Webhookエンドポイントの登録にはPeerlytics APIキーを使います。同じキーでPeerlytics APIも認証されます。