PV サービス webhook を設定する

PV サービス webhook を設定して、KWS から検証成功通知イベントを受け取る方法を紹介します。

はじめに

保護者が PV サービスを使用して ID 検証に成功すると、KWS は webhook コールを通じて parent-verified イベントを送信することでシステムに通知します。

ユーザー側で webhook を設定するには、次が必要です。

注記:テスト環境およびプロダクション環境には、それぞれ一意の webhook シークレット コードがあります。

webhook URL を設定する

  1. [Parent Verification] ビューで、[Successful verification webhook URL (検証成功の webhook URL)] を入力します。これは、KWS が検証に成功したことを示す webhook を送信するアドレスです。

    重要:

    • webhook の URL には、攻撃者が不正操作しやすい情報を含めないでください (簡単に反復処理できるような数字 ID など)。

    • URL に特殊文字を含めないでください。

  2. [Publish to Test (公開してテスト)] をクリックします。

シークレット コードを使用してシグネチャを生成する

[Publish to Test] をクリックすると、[Parent Verification] タブに Webhook シークレット コード** が表示されます。

画像をクリックするとフルサイズで表示されます。

この例では、シークレット コードを使用してシグネチャを作成する方法を示します。

KWS から webhook が送信されます。webhook コールは、イベント固有のペイロードを折り返す共通の構造体を持つ HTTPS POST です。

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
"name": "webhook-name",
"time":"ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

POST コールのヘッダーには、次の構造体が含まれています。

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

は、ヘッダーのタイムスタンプ値、[Parent Verification] タブの製品の統合詳細に表示される Webhook シークレット コード、 および POST ボディを使用し、HMAC_SHA256 を介して生成されます。

const timestamp =   /* extracted value of 't=' from the header */;
const body =        /* raw request body as UTF-8 string */;
const secretKey =   /* secret key, as provided in the Developer Portal */;
const signature = crypto
.createHmac('sha256', secretKey)
.update('${timestamp}.${body}')
.digest('hex');

製品側で、上記のコードとタイムスタンプ、Webhook シークレット コード、および POST ボディを使用して、同じシグネチャを作成する必要があります。作成したシグネチャが webhook コールのヘッダーで渡された v1 シグネチャと一致する場合、webhook は送信されたものであることを確認できます。

Web サーバー/Web アプリケーションを介してパブリック エンドポイントが表示されます (他の API エンドポイントのビルド方法と同様)。このエンドポイントは、次に示す POST ボディを使用し、シグネチャ ヘッダーを検証します。

注記:生の POST ボディを使用する点が重要です。JSON をパースして再文字化しようとしないでください。JSON ライブラリ実装における不一致が原因でシグネチャのミスマッチが生じる可能性があるためです。

### POST ボディ構造体

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]
体
{
"name": "webhook-name",
"time":"ISO8601 timestamp",
"orgId": "uuid",
"productId": "uuid" | null,
"environmentId": "uuid" | null,
"payload": { ... type-specific payload ... }
}

シグネチャ

webhook が KWS から送信されたものであることを確認するには、生成した v1 シグネチャと KWS から受信した webhook コールのヘッダーの v1 シグネチャを比較します。シグネチャが一致した場合、そのコールが KWS から送信されたものであることを確認できます。

シグネチャは、16 進数形式 (小文字) の HMAC_SHA256 ハッシュで、秘密キーは [Parent Verification] タブで設定した Webhook シークレット コード です。

シグネチャは「x-kws-signature」ヘッダー内に以下の形式で送信されます。

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

注記:現状では、v1 シグネチャが 1 つ含まれますが、以下の場合は複数のシグネチャをヘッダーに含めることができます。

  • シグネチャ キー ローテーションに対応しています (移行期間は前回のキーと現在のキーが送信されます)。

  • シグネチャのアルゴリズムは変更します (移行期間は、v2 シグネチャが v1 シグネチャと一緒に送信されます)。

v1 シグネチャを生成するアルゴリズムは、シグネチャ ヘッダーに含まれるタイムスタンプの HMAC_SHA256、ピリオド「.」、そして生のリクエスト ボディの順です。webhook のシークレット コードで HMAC を初期化します。

次に例を挙げます。

const timestamp = /* extracted value of ‘t=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* the webhook secret code from the Parent Verification tab. */;
const signature = crypto
.createHmac('sha256', secretKey)
.update(`${timestamp}.${body}`)
.digest('hex');

注記:webhook URL はあえてシグネチャ アルゴリズムに含めていません。URL リクエストが変更された際に、reverse-proxies / load-balancers などの背後にあるサービス内でシグネチャ検証を容易にするためです。

webhook の再試行動作

webhook の再試行動作は、サーバーが POST リクエストに返すステータス コードに依存します。

ステータス コード

動作

200 から 299 まで

コールは成功したと考えられる。

0 から 199、500 以上、タイムアウト (3 秒) またはネットワーク エラー

一時的な失敗。

コールは、次の遅延の後、エクスポネンシャル バックオフで再試行される。

  • 30 秒

  • 1 分 (合計 1.5 分)

  • 2 分 (合計 3.5 分)

  • 4 分 (合計 7.5 分)

  • 8 分 (合計 15.5 分)

  • 16 分 (合計 31.5 分)

  • 32 分 (合計 1 時間 3.5 分)

  • 1 時間 4 分 (合計 2 時間 7.5 分)

  • 2 時間 8 分 (合計 4 時間 15.5 分)

  • 4 時間 16 分 (合計 8 時間 31.5 分)

  • 8 時間 32 分 (合計 17 時間 3.5 分)

  • 17 時間 4 分 (合計 34 時間 7.5 分)

最後の再試行が失敗した場合 (ステータス コードは 400 以上)、コールは失敗したと記録される。

次のステップ

保護者が利用可能な検証メソッドを選択します