署名の不一致
最も一般的な原因は、正確な生の本文ではなく、解析された JSON に署名すること、または要求ヘッダーとは異なるタイムスタンプを使用することです。
Webhook テスター
Webhook をテスト署名を確かめる
サンプル本文を編集し、HMAC-SHA256 署名と cURL リクエストを生成。テスト環境で検証ロジックを確認できます。
01
テストを設定
URL、テスト用キー、タイムスタンプを入力します。
署名はブラウザーで計算します。テスト用キーを使用してください。
BoltUtil のヘッダーと同じミリ秒単位の Unix タイムスタンプです。
02
本文を編集して署名を生成
JSON の編集に合わせて署名と cURL が更新されます。
署名
HMAC-SHA256有効なキー、タイムスタンプ、JSON を入力してください。
タイムスタンプ、本文の原文、テスト用キーから計算します。
有効な JSON
cURL / POSTテストリクエスト
有効な URL、キー、タイムスタンプ、JSON を入力してください。USDC 注文の模擬通知です。USDT に変更できます。注文、アドレス、取引ハッシュは例であり、支払いの証明ではありません。
自動送信はしません。テスト環境で cURL を手動実行してください。
HMAC_SHA256(timestamp + "." + rawBody, secret)- 01
生の本体を確認する
JSON を解析する前に、ヘッダーのミリ秒のタイムスタンプと正確な生の本文を使用して HMAC を計算します。空白、改行、フィールドの順序は署名に影響します。
- 02
タイミングセーフな比較を使用する
受信した署名を、言語ランタイムによって提供される定数ヘルパーと比較します。
- 03
安全に録画してから、2xx を返します
イベントを記録するか、永続的な内部キューにイベントを入れた後のみ、成功を返します。
Webhookのトラブルシューティング
一致していませんか?ここから始めましょう
元の本文、シークレット、および応答ステータスを確認して、問題を特定します。
間違った秘密
マーチャントエンドポイント用に構成された Webhook シークレットを使用します。 API キーと Webhook シークレットは、別の認証情報として扱う必要があります。
ボディパーサーがペイロードを変更しました
JSON ミドルウェアは、ペイロードを並べ替えたり再フォーマットしたりできます。 HMAC 署名を検証する場合は、解析する前に生の本文をキャプチャします。
エンドポイントが非 2xx を返す
2xx 以外は配信失敗です。再試行は通知の種類、HTTP ステータス、ポリシーにより異なります。
処理はべき等ではありません
注文 ID と状態、または一意のイベント ID で重複を排除します。1 つの取引ハッシュに複数の送金が含まれることがあります。
耐久性の前に成功
イベントをデータベースまたはキューに書き込んだ後でのみ、HTTP 2xx を返します。そうしないと、クラッシュによって完了した支払い通知が失われる可能性があります。
FAQ
デバッグ中の質問
署名の検証、応答、および二重配信。
Webhook 署名の検証が失敗するのはなぜですか?
正確な未処理のリクエスト本文、タイムスタンプ ヘッダー、および構成された Webhook シークレットを確認します。解析された JSON または再フォーマットされた本体に署名すると、通常は異なる HMAC が生成されます。
Webhook エンドポイントは応答本文で SUCCESS を返す必要がありますか?
不要です。BoltUtil は HTTP ステータスで判断し、2xx は受信成功です。先に検証してイベントを保存してください。
Webhook 配信の重複はどのように処理すればよいですか?
注文 ID と状態、またはイベント ID に一意制約やアトミック操作を使います。取引ハッシュだけでは不十分です。
エンドポイントはいつ HTTP 2xx を返すべきですか?
検証と保存後に 2xx を返します。失敗時は適切なエラーを返し、再試行は通知の種類とポリシーに従います。