Webhooksの概要
Webhooksは、チャレンジステータスの変更や確認結果など、k-IDの重要なイベントについてサーバーに通知します。各プロダクトの開発者設定で、Compliance Studioでwebhook URLとシークレットを設定します。
ペイロードにはeventTypeとdataオブジェクトが含まれます。ペイロードスキーマについては、イベントタイプを参照してください。
イベントタイプ
| イベントタイプ | 説明 |
|---|---|
Challenge.StateChange | 保護者の同意チャレンジの状態が変更されたときに発行される |
Verification.Result | 確認試行の結果とともに発行される |
Verification.Revoke | 以前に合格した認証が取り消されたときに発行される |
Account.Delete | アカウントが削除されたときに発行される |
AgeAssurance.Result | Age Assurance評価の結果とともに発行される（非推奨、Verification.Resultに置き換え） |
ParentalConsent.Granted | 保護者の同意が付与されたときに発行される |
Session.ChangePermissions | 親によってセッション権限が変更されたときに発行される |
Session.Delete | セッションが削除されたときに発行される |
Test | webhookが正しく機能していることを確認するために使用される |
署名の検証
設定されたwebhookシークレットでwebhookリクエストを検証します。
ヘッダー
各リクエストとともに送信されるヘッダー：
X-Signature-Timestamp: UNIXエポック秒X-Signature-Hmac-Sha256: （タイムスタンプ + 生の本文）のHMAC SHA-256。webhookシークレットをキーとして使用し、16進数エンコード（小文字）
期待される動作
- 有効な署名の場合は
200を返す - 無効な署名の場合は
401を返す
実装の詳細については、Webhookリクエストの検証を参照してください。
配信、リトライ、リカバリー
配信保証
k-IDはat-least-once（少なくとも1回）の保証でwebhookイベントを配信します。エンドポイントは同じイベントを複数回受信する可能性があるため、ハンドラーを冪等に設計してください。data.idフィールド（確認またはチャレンジID）を使用して、既に処理したイベントの重複を排除してください。
リトライポリシー
エンドポイントが200以外のステータスコードを返すか、リクエストがタイムアウトした場合、k-IDは2回リトライします：
| 試行 | 前回の試行からの遅延 |
|---|---|
| 1回目のリトライ | 5秒 |
| 2回目のリトライ | 10秒 |
最初の試行と2回のリトライ（合計3回の試行）の後、k-IDはそのイベントの配信を停止します。
受信できなかったwebhookの処理
サーバーがダウンしていたか、webhookが正常に配信されなかった場合、フローを開始した際に保存したIDを使用して、サーバーから関連するステータスエンドポイントをポーリングして回復してください：
- 確認:
GET /age-verification/get-statusに確認IDを指定 - チャレンジ:
GET /challenge/get-statusにチャレンジIDを指定
フローを開始した際に受け取る確認またはチャレンジIDを常に保存してください。webhookハンドラーが想定された時間内に結果を受信しない場合、対応するget-statusエンドポイントを呼び出して現在の状態を取得します。このリダイレクト→ポーリングのパターンにより、すべてのwebhook配信が失敗しても結果を見逃すことがありません。
冪等性
webhookイベントは冪等です。同じイベントは複数回配信される可能性があります。例えば、ネットワークの問題により配信ステータスが曖昧になった場合などです。イベントに対してアクションを起こす前に、そのイベントが既に処理済みかどうかを常に確認してください。簡単な方法として、処理済みのイベントID（data.idフィールド）を追跡して重複をスキップすることができます。