> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.6mm.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server.

# ウェブフック署名検証と冪等性

Webhookは非同期のビジネス状態変更をパートナーのバックエンドに通知します。配信が再試される可能性があるため、すべての受信者は信頼されたデータを解析する前に署名を検証し、イベントを冪等的に処理しなければなりません。

<h2 id="webhook-headers">
  ウェブフックヘッダー
</h2>

| ヘッダー            | 概要                      |
| --------------- | ----------------------- |
| X-エージェントタイムスタンプ | Unixのタイムスタンプは数秒で表示されます。 |
| X-エージェント-ノンス    | リプレイプロテクション・ナンス。        |
| X-エージェント-シグネチャー | HMAC- 署名SHA256 。        |

```text
timestamp + nonce + rawBody
```

署名値を再構築する際は、 HTTP 上で受信した正確な生のリクエストボディを使用します。まず解析して再シリアライズ JSON 、空白やフィールドの順序を変え、異なる署名を生成できます。

<h2 id="verification-flow">
  検証フロー
</h2>

1. タイムスタンプ、ノンス、署名ヘッダーを読み取る。
2. 修正されていない生のリクエストボディを取得する。
3. `timestamp + nonce + rawBody`を築く。
4. パートナーとの秘密HMACSHA256計算API。
5. 計算された署名と受信された署名を定時比較を用いて比較する。
6. 承認されたタイムスタンプの新鮮さおよびノンス再利用チェックを適用します。
7. 検証が成功した後にのみイベントを解析・処理する。

公式の Agent SDK 検証器が利用可能になった場合は、独立した署名コードを維持する代わりにそれを使いましょう。

<h2 id="order-idempotency">
  位数冪起等
</h2>

| 事件          | 取り扱い                                     |
| ----------- | ---------------------------------------- |
| 最初の転送申請     | 世界的にユニークな agentOrderNoを作りましょう。           |
| HTTP タイムアウト | 新しい agentOrderNo を作成する前に、元のにクエリを行ってください。 |
| PROCESSING  | ウェブフックやクエリの注文状況を待ちましょう。                  |
| 繰り返しウェブフック  | 冪等性キーと最終状態で重複を消す。                        |

<h2 id="recommended-idempotency-record">
  推奨冪等性記録
</h2>

繰り返し配達を認識し安全に回復できる十分な情報を保存する:

| フィールド           | 目的                      |
| --------------- | ----------------------- |
| イベントキーまたはビジネスキー | 通知や操作を一意に識別します。         |
| パートナー注文番号       | イベントを元のリクエストに結びつけます。    |
| ペイロードハッシュ       | 重複するペイロードの特定に役立ちます。     |
| 現在の処理状態         | 受領、処理、成功・失敗した仕事の区別。     |
| 最終的な事業状況        | ターミナルアクションが二度適用されるのを防ぐ。 |
| 処理済みタイムスタンプ     | 調査および保持方針を支援します。        |

可能な限り、ビジネス変更と冪등 記録を同じトランザクションにコミットしてください。繰り返しイベントを行うと、残高、注文、ユーザーの変更を再度適用する代わりに既知の結果を返すべきです。

<h2 id="timeout-and-retry-rule">
  タイムアウトと再挑戦ルール
</h2>

HTTPタイムアウトは元のリクエストが失敗したことを証明しません。元の`agentOrderNo`を使って操作を照会するか、ウェブフックを待ってから次の処理が必要かどうか判断してください。タイムアウト後に新しい受注番号を作成すると、重複した資金移動を引き起こす可能性があります。

<h2 id="production-checklist">
  生産チェックリスト
</h2>

* 解析やビジネス処理 JSON 署名を確認する。
* 解析されたペイロードとは独立して生のボディを保存する。
* 承認された統合ポリシーに従って、古いリクエストや再再生リクエストを拒否する。
* イベント処理を繰り返しかつ順序外の配信に安全にすること。
* イベントID、パートナー注文番号、処理結果、リクエスト時間を記録する。
* ログやサポート添付ファイルから秘密情報や署名値を黒塗りすること。

<h2 id="related-docs">
  関連文書
</h2>

#### [秘密と HMAC 署名](/ja/sdk/security/secrets-signing)

リクエストおよびウェブフックの検証に使用される API 秘密を保護しましょう。

#### [Agent SDK 概要](/ja/sdk/agent-sdk/overview)

バックエンド統合ワークフロー全体を見直しましょう。

#### [SDK トラブルシューティング](/ja/sdk/security/troubleshooting)

拒否された署名、繰り返された出来事、保留中の作業を調査します。