はじめに
保護者が PV サービスを使用して ID 検証に成功すると、KWS は webhook コールを通じて parent-verified イベントを送信することでシステムに通知します。
ユーザー側で webhook を設定するには、次が必要です。
- KWS が webhook を送信する URL を指定します。
- シグネチャ を生成します。 これは、Webhook シークレット コード を使用して、KWS の [Parent Verification (保護者検証)] タブの製品の統合詳細で指定します。シークレット コードは、webhook が KWS からの正式なコールであることを確認するためにペイロードの署名に使用されます。
注記：テスト環境およびプロダクション環境には、それぞれ一意の webhook シークレット コードがあります。
webhook URL を設定する
-
[Parent Verification] ビューで、[Successful verification webhook URL (検証成功の webhook URL)] を入力します。これは、KWS が検証に成功したことを示す webhook を送信するアドレスです。
重要：
- webhook の URL には、攻撃者が不正操作しやすい情報を含めないでください (簡単に反復処理できるような数字 ID など)。
- URL に特殊文字を含めないでください。
-
[Publish to Test (公開してテスト)] をクリックします。
シークレット コードを使用してシグネチャを生成する
[Publish to Test] をクリックすると、[Parent Verification] タブに Webhook シークレット コード が表示されます。
クリックしてフルサイズ表示
例
この例では、シークレット コードを使用してシグネチャを作成する方法を示します。
KWS から webhook が送信されます。webhook コールは、イベント固有のペイロードを折り返す共通の構造体を持つ HTTPS POST です。
POST コールのヘッダーには、次の構造体が含まれています。
<signature> は、ヘッダーのタイムスタンプ値、[Parent Verification] タブの製品の統合詳細に表示される Webhook シークレット コード、 および POST ボディを使用し、HMAC_SHA256 を介して生成されます。
製品側で、上記のコードとタイムスタンプ、Webhook シークレット コード、および POST ボディを使用して、同じシグネチャを作成する必要があります。作成したシグネチャが webhook コールのヘッダーで渡された v1 シグネチャと一致する場合、webhook は送信されたものであることを確認できます。
Web サーバー/Web アプリケーションを介してパブリック エンドポイントが表示されます (他の API エンドポイントのビルド方法と同様)。このエンドポイントは、次に示す POST ボディを使用し、シグネチャ ヘッダーを検証します。
注記：生の POST ボディを使用する点が重要です。JSON をパースして再文字化しようとしないでください。JSON ライブラリ実装における不一致が原因でシグネチャのミスマッチが生じる可能性があるためです。
POST ボディ構造体
シグネチャ
webhook が KWS から送信されたものであることを確認するには、生成した v1 シグネチャと KWS から受信した webhook コールのヘッダーの v1 シグネチャを比較します。シグネチャが一致した場合、そのコールが KWS から送信されたものであることを確認できます。
シグネチャは、16 進数形式 (小文字) の HMAC_SHA256 ハッシュで、秘密キーは [Parent Verification] タブで設定した Webhook シークレット コード です。
シグネチャは「x-kws-signature」ヘッダー内に以下の形式で送信されます。
注記：現状では、v1 シグネチャが 1 つ含まれますが、以下の場合は複数のシグネチャをヘッダーに含めることができます。
- シグネチャ キー ローテーションに対応しています (移行期間は前回のキーと現在のキーが送信されます)。
- シグネチャのアルゴリズムは変更します (移行期間は、v2 シグネチャが v1 シグネチャと一緒に送信されます)。
v1 シグネチャを生成するアルゴリズムは、シグネチャ ヘッダーに含まれるタイムスタンプの HMAC_SHA256、ピリオド「.」、そして生のリクエスト ボディの順です。webhook のシークレット コードで HMAC を初期化します。
例：
注記：webhook URL はあえてシグネチャ アルゴリズムに含めていません。URL リクエストが変更された際に、reverse-proxies / load-balancers などの背後にあるサービス内でシグネチャ検証を容易にするためです。
webhook の再試行動作
webhook の再試行動作は、サーバーが POST リクエストに返すステータス コードに依存します。
| ステータス コード | 動作 |
|---|---|
| 200 から 299 まで | コールは成功したと考えられる。 |
| 0 から 199、500 以上、タイムアウト (3 秒) またはネットワーク エラー | 一時的な失敗。コールは、次の遅延の後、エクスポネンシャル バックオフで再試行される。
|
| 400+ | 最後の再試行が失敗しました。コールは失敗したと記録されました。 |
次のステップ
保護者が利用可能な検証メソッド (地域により異なります) を選択します。