メインコンテンツに移動

Webhooks

Webhooksを使用すると、データが利用可能かどうかを確認するためにAPIをポーリングするのではなく、k-ID Engineで発生しているイベントをリアルタイムで購読できます。

Webhooksとは？​

Webhooksは、さまざまな目的に使用できます。例：

  1. チャレンジ完了結果の処理
  2. 年齢確認結果の処理
  3. k-IDセッションの変更の処理

Webhooksの設定​

WebhooksはCompliance Studioで設定され、イベントが発生したときにk-ID Engineが呼び出すURLを指定します。URLは安全なHTTPS URLである必要があります。k-ID Engineは、イベントデータを含むJSONペイロードでURLにPOSTリクエストを送信します。

情報

Webhooksは個別の製品に関連付けられています。複数のk-ID製品がある場合、すべての製品に同じエンドポイントを使用できますが、API呼び出し（たとえば/session/get）を行うために、正しい製品固有のk-ID APIキーを取得する必要があることに注意することが重要です。

Webhooksは、Compliance Studioの製品の開発者設定セクションで設定できます。

Webhook Publisher Dashboard

Webhookイベント構造​

webhook URLに送信されるJSONペイロードには、以下のフィールドが含まれます：

  • eventType - 発生したイベントのタイプ。
  • data - イベントに関連付けられたデータ。

X-Event-Typeヘッダーもイベントタイプとともに送信されます。

Webhookリクエストの検証​

Webhooksはパブリックインターネット経由で送信されるため、リクエストがk-IDから来ていることを検証することが重要です。これは、設定されたwebhookシークレットを使用してイベントペイロードの署名を検証することで行われます。

すべてのリクエストには、以下のヘッダーが含まれます：

  • X-Signature-Timestamp - リクエストのタイムスタンプ（UNIXエポック秒）。
  • X-Signature-Hmac-Sha256 - UTF-8エンコードされたタイムスタンプとリクエスト本文を連結し、webhookシークレットをキーとしてHMAC SHA-256キー付きハッシュを計算したもの。小文字の16進数文字列としてエンコードされます。

署名が無効な場合、リクエストは401ステータスコードで拒否される必要があります。検証された署名を持つwebhookリクエストは、200ステータスコードで処理および受け入れられます。

検証コードの例​

const crypto = require("crypto");

// [Compliance Studio](/compliance-studio/products/creating-new-product)で設定されたwebhookシークレット。
const SECRET = "your-secret";

const timestamp = req.get("X-Signature-Timestamp");
const signature = req.get("X-Signature-Hmac-Sha256");
const body = req.rawBody; // 生のリクエスト本文（文字列として）。

// 期待される署名を計算する。
const hmac = crypto.createHmac("sha256", SECRET);
hmac.update(timestamp + body);
const expectedSignature = hmac.digest("hex");

// 署名を安全に比較する。
if (
  !crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  )
) {
  return res.status(401).end("Unauthorized");
}

イベントタイプ​

イベントタイプ説明
Challenge.StateChange親の同意チャレンジの状態が変更されたときに発行される
Verification.Result確認試行の結果とともに発行される
Account.Deleteアカウントが削除されたときに発行される
AgeAssurance.ResultAge Assurance評価の結果とともに発行される（非推奨、Verification.Resultに置き換え）
ParentalConsent.Granted親の同意が付与されたときに発行される
Session.ChangePermissions親によってセッション権限が変更されたときに発行される
Session.Deleteセッションが削除されたときに発行される
Testwebhookが正しく機能していることを確認するために使用される