Webhooks(ウェブフック)

Webhooksを利用することで、k-IDエンジン内で発生するイベントをリアルタイムで受け取ることができ、 APIを定期的にポーリングしてデータの有無を確認する必要がなくなります。

Webhooksは、以下のようなさまざまな目的で利用することができます：

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

Setting Up Webhooks (ウェブフックの設定)

Webhooksは、Developer Portal上で設定します。イベントが発生した際にk-IDエンジンが 呼び出すURLを指定することで構成されます。指定するURLは、HTTPSで保護されたセキュアなURLである必要があります。 k-IDエンジンは、イベントデータを含むJSON形式のペイロードをPOSTリクエストとして指定されたURLに送信します。

Webhooksは各Product単位で紐付けられます。複数のk-ID　Productをお持ちの場合、同じエンドポイントを 使い回すことも可能ですが、APIコール（例：/session/get）を行う際には、対象Product専用のk-ID APIキーを必ず使用する必要がある点にご注意ください。

Webhooks can be configured on Developer Settings of a selected product. You can access this page at /products/[productId]/developer.

Webhooks Configuration Page（Webhooksの構成と管理ページ）

Webhooks セクションは、Developer Settings（開発者設定） 内にあり、特定のイベントが発生した際に k-ID（k-ID） が呼び出す HTTPS URL を設定することができます。アプリケーションに必要な Webhook の URL を入力し、Save（保存） をクリックすることで、設定内容がシステムに反映されます。変更内容は、現在の設定に基づいて自動的に適切な環境（Test Mode（テストモード） または Live Mode（ライブモード））に適用されます。詳しくは こちらのガイド をご参照ください。

これにより、テスト環境でも本番環境でも、イベント通知がアプリケーションに正しくかつ安全にルーティングされることが保証されます。

Note（注）: Save（保存） ボタンは Push to Test（テストにプッシュ） や Publish Live（本番に公開） ボタンとは異なります。Webhookの保存や更新はユーザー体験に直接影響を与えることはありませんが、Push to Test（テストにプッシュ） や Publish Live（本番に公開） を使用して行う変更は、ユーザー体験全体に影響する可能性があり、k-ID（k-ID） チームによる事前の確認が必要になる場合があります。

さらに、エンドポイントが正しく設定されているかをシークレットの有無にかかわらず確認できる Test Webhook（Webhookテスト） ボタン があります。Webhookリクエストの検証方法については、ドキュメントの該当セクション をご覧ください。このボタンはテストイベントをシミュレートし、その内容は テストイベントに関するドキュメントセクション に記載されています。

Webhook Event Structure（Webhookイベント構造）

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

• eventType - 発生したイベントの種類
• data - イベントに関連するデータ

また、イベントタイプを示す X-Event-Type ヘッダーも併せて送信されます。

Validating Webhook Requests（Webhookリクエストの検証）

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

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

• X-Signature-Timestamp - リクエストのタイムスタンプ （Unixエポック秒）
• X-Signature-Hmac-Sha256 - タイムスタンプとリクエスト本文（どちらもUTF-8エンコード）を 連結したものに対して、Webhookシークレットを鍵としてHMAC SHA-256でハッシュ化し、 16進の小文字文字列としてエンコードしたもの

署名が無効な場合、そのリクエストは**401ステータスコード（401ステータスコード）**で 拒否されるべきです。

コード例

const crypto = require("crypto");

// Your webhook secret, configured in the Developer Portal.
const SECRET = "your-secret";

const timestamp = req.get("X-Signature-Timestamp");
const signature = req.get("X-Signature-Hmac-Sha256");
const body = req.rawBody; // Raw request body, as a string.

// Compute the expected signature.
const hmac = crypto.createHmac("sha256", SECRET);
hmac.update(timestamp + body);
const expectedSignature = hmac.digest("hex");

// Compare signatures securely.
if (
  !crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expectedSignature, "hex")
  )
) {
  return res.status(401).end("Unauthorized");
}

Webhook Event Types（Webhookイベントタイプ）

利用可能なイベントタイプは以下の通りです：

• Test（テストイベント
• Challenge.StateChange（チャレンジ状態の変更）
• Session.ChangePermissions（セッションの権限変更）
• Session.Delete（セッションの削除）
• Verification.Result（年齢確認結果）
• AgeAssurance.Result（年齢保証結果）

Test（テスト）

このイベントタイプは、Webhookが正しく動作しているかを確認するために使用されます。 Webhook受信側でこのイベントを適切に処理する必要があります。

例：ペイロード（Example payload）：

{
  "eventType": "Test",
  "data": {
    "id": "12345678-1234-1234-1234-123456789abc"
  }
}

Challenge State Change（チャレンジ状態の変更）

プロパティ（Properties）:

• id - チャレンジID
• productId - プロダクトID
• status - PASS（成功）、FAIL（失敗）、または IN_PROGRESS（進行中）のいずれか
• sessionId（オプション）- PASS の場合に含まれるセッションID
• approverEmail（オプション）- PASS の場合に含まれる承認者のメールアドレス
• kuid（オプション）- PASS の場合に含まれる k-ID ユーザーID

例：ペイロード（Example payload）：

{
  "eventType": "Challenge.StateChange",
  "data": {
    "id": "683409f1-2930-4132-89ad-827462eed9af",
    "productId": 42,
    "status": "PASS",
    "sessionId": "0ad1641f-c154-4cc2-8bb2-74dbd0de7723",
    "approverEmail": "user@example.com",
    "kuid": "123456"
  }
}

Session Change Permissions（セッション権限の変更）

このイベントタイプは、**k-ID Family Portal（k-IDファミリーポータル）**内で親が直接セッションの権限を変更した場合にのみ、Webhook受信先に送信されます。
プレイヤーの誕生日などによって年齢カテゴリが変わり、管轄内でより多くの機能にアクセスできるようになった場合などは、ゲーム側で /session/get API を呼び出して、変更後の Session 権限を取得する必要があります。

プロパティ（Properties）:

• id - セッションID
• productId - プロダクトID

例：ペイロード（Example payload）：

{
  "eventType": "Session.ChangePermissions",
  "data": {
    "id": "78c299b2-5c33-4bde-84fe-8fc950fc7a96",
    "productId": 42
  }
}

Session Delete（セッションの削除）

プロパティ（Properties）:

• id - セッションID
• productId - プロダクトID

例：ペイロード（Example payload）：

{
  "eventType": "Session.Delete",
  "data": {
    "id": "2d064cf7-0726-4193-b19a-8bd387937e60",
    "productId": 42
  }
}

Verification Result（年齢確認結果）

プロパティ（Properties）:

• id - 一意の検証ID
• status - PASS（成功）または FAIL（失敗）
• ageCategory（オプション）- 推定される年齢カテゴリ。adult（成人）、digital-youth（デジタルユース）、digital-minor（デジタルマイナー）のいずれか。status が PASS の場合にのみ設定されます。
• method（オプション）- 使用された確認手段。id-document（身分証明書）、credit-card（クレジットカード）、age-estimation（年齢推定）のいずれか。status が PASS の場合にのみ設定されます。
• failureReason（オプション）- 検証失敗の理由。age-criteria-not-met（年齢基準未達）または max-attempts-exceeded（最大試行回数超過）。status が FAIL の場合にのみ設定されます。
• age（オプション）- 年齢の詳細。これは status が PASS かつ、該当する検証シナリオで年齢を返すよう構成されている場合のみ含まれます。

age のプロパティ（age properties）:

• low - 推定年齢の下限。IDドキュメントなどの厳密な方法で確認された場合は、正確な年齢となります。
• high - 推定年齢の上限。IDドキュメントなどの厳密な方法で確認された場合は、正確な年齢となります。

例：ペイロード（Example payload）：

{
  "eventType": "Verification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

Age Assurance Result（年齢保証結果）

プロパティ（Properties）:

• id - 一意の検証ID
• status - PASS（成功）または FAIL（失敗）
• ageRange（オプション）- 推定された年齢範囲の詳細

ageRange のプロパティ（ageRange properties）:

• minAge - 推定される最小年齢
• maxAge - 推定される最大年齢

例：ペイロード（Example payload）：

{
  "eventType": "AgeAssurance.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageRange": {
      "minAge": 18,
      "maxAge": 25
    }
  }
}