> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legitmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks はじめに

> 鑑定ステータスの変更、画像の拒否、サービスリクエストの無効化時にリアルタイム通知を受信します。

Legitmark は Webhook を通じて、HTTPS エンドポイントにリアルタイムのイベント通知を送信します。サービスリクエストのステータスが変更されたとき、品質管理で画像が拒否されたとき、またはリクエストが無効化されたとき、エンドポイントにイベントペイロードを含む `POST` リクエストが届きます。

配信には自動リトライと指数バックオフが含まれます。

<Note>
  Webhook 送信先のセットアップが必要ですか？[はじめに](/ja/partner/getting-started)の手順に従ってください。
</Note>

## 要件

Webhook エンドポイントは以下の要件を満たす必要があります：

| 要件            | 詳細                                                                                  |
| ------------- | ----------------------------------------------------------------------------------- |
| **HTTPS**     | 送信先 URL は HTTPS を使用すること                                                             |
| **200 レスポンス** | 受信確認として 30 秒以内に `200` ステータスを返すこと                                                    |
| **冪等性**       | 重複配信を処理すること — イベントタイプごとの重複排除戦略は [Webhook 処理ガイド](/ja/webhook-reference/handling) を参照 |

## イベントタイプ

すべての送信先は自動的にすべてのイベントタイプを受信します。イベントごとのフィルタリングはありません。

<CardGroup cols={3}>
  <Card title="state_change" icon="arrows-rotate" href="/ja/webhook-reference/events#state_change">
    サービスリクエストのステータス変更 — 品質管理、鑑定の進捗、最終結果。
  </Card>

  <Card title="media_rejected" icon="image-slash" href="/ja/webhook-reference/events#media_rejected">
    アップロードされた画像が品質管理で拒否された。
  </Card>

  <Card title="invalidate_sr" icon="circle-xmark" href="/ja/webhook-reference/events#invalidate_sr">
    サービスリクエストがキャンセルまたは処理不能。
  </Card>
</CardGroup>

## 共通ペイロードフィールド

すべての Webhook イベントに以下の基本フィールドが含まれます：

| フィールド          | 型                | 説明                                                       |
| -------------- | ---------------- | -------------------------------------------------------- |
| `event_type`   | `string`         | イベント識別子（`state_change`、`media_rejected`、`invalidate_sr`） |
| `sr_uuid`      | `string`         | サービスリクエスト UUID                                           |
| `reference_id` | `string \| null` | 貴社の内部商品 ID（サービスリクエスト作成時に設定した `external_id`）              |
| `timestamp`    | `string`         | イベント発生時の ISO 8601 タイムスタンプ                                |

## リトライ

配信失敗（非 2xx レスポンスまたはタイムアウト）は指数バックオフで自動リトライされます：

| 試行回数 | 遅延     |
| ---- | ------ |
| 1    | 即時     |
| 2    | 約 5 秒  |
| 3    | 約 5 分  |
| 4    | 約 30 分 |
| 5    | 約 2 時間 |

すべてのリトライが尽きると、メッセージは失敗としてマークされます。配信状況の確認と手動リトライは [Legitmark ダッシュボード](https://app.legitmark.com/settings/developer)から行えます。

## テスト

エンドポイントがまだ準備できていない場合は、[Svix Play](https://play.svix.com/) を使用してテスト用の一時的な Webhook URL を生成できます。生成された URL を[開発者設定](https://app.legitmark.com/settings/developer)に Webhook 送信先として貼り付け、テストイベントを送信して、リアルタイムでペイロードを確認してください。

## 次のステップ

<CardGroup cols={2}>
  <Card title="イベントタイプ" icon="bolt" href="/ja/webhook-reference/events">
    各イベントタイプの詳細なペイロード構造。
  </Card>

  <Card title="Webhook 処理ガイド" icon="code" href="/ja/webhook-reference/handling">
    コード例、ベストプラクティス、セキュリティガイダンス。
  </Card>
</CardGroup>