FACEIO Webhook APIリファレンス

ユーザーの登録、FACEIO による認証、または Facial ID の削除が行われたときに HTTPS POST 通知を受け取ります。Webhooks を使用して、フロントエンドの状態だけに依存せず、顔認証イベントとバックエンドを同期します。

FACEIO Consoleを開く

FACEIO Consoleでアプリケーションを作成または選択し、HTTPSエンドポイントを登録して、アプリケーションに割り当てられたWebhook tokenを取得します。

FACEIO Webhookの概要

FACEIOの登録、認証、Facial ID削除に対応するサーバー側イベント配信

FACEIO Webhooksは、新しい顔の登録、顔の認証成功、またはFacial IDの削除後にバックエンドへ通知します。これらのサーバー側イベントを使用して、アカウント情報とFACEIOの処理結果を整合させます。

イベントが発生すると、FACEIO はHTTPS POST リクエストを、アプリケーションに設定した Webhook endpoint URL へ送信します。JSON payload には、一意の Facial ID、アプリケーションの Public ID、イベント名、クライアント IP アドレス、タイムスタンプ、利用可能な場合の関連 payload、推定年齢や性別などの登録情報が含まれます。

Webhookイベントは、バックエンドの記録更新、監査ログの作成、独自のサーバー側処理の開始に使用できます。payloadを処理する前に受信Webhookを必ず検証し、FACEIOのセキュリティのベストプラクティスに従ってください。

リアルタイム更新

ユーザーの登録、認証、またはFacial ID削除の完了時にイベント通知を受け取ります。

バックエンド同期

ブラウザーのコールバックだけに依存せず、信頼できるサーバー側イベントからアカウント情報を更新します。

FACEIO Webhookを設定

バックエンドへのイベント配信が必要なFACEIOアプリケーションごとにwebhookエンドポイントを設定します。エンドポイントはHTTPS経由のJSONを受け取り、 WWW-Authenticate トークンを検証して、すぐに成功レスポンスを返してください。

1

FACEIO Consoleを開く

FACEIO Console ↗にログインします。

2

Application Managerを開く

FACEIO Console のメイン画面からApplication Manager ↗を開きます。

3

対象アプリケーションを選択

登録、認証、Facial ID削除の通知を送信するFACEIOアプリケーションを選択します。

4

Webhooksタブを開く

アプリケーションマネージャー画面の WEBHOOKS タブに移動します。

5

エンドポイントURLを追加

FACEIOの イベントを受け取るwebhookエンドポイントURLを入力し、アプリケーション設定を保存します。

✓

イベントの受信を開始

イベントが発生すると、FACEIO は Webhook URL へ HTTPS POST リクエストを送信します。リクエストには、以下のJSON payload が含まれます。

HTTPリクエストの詳細

Webhookエンドポイントは、イベントが発生するたびにFACEIOから送信されるHTTPSリクエストを処理する必要があります。リクエスト形式は次のとおりです。

HTTPメソッド POST
Content-Type application/json
POSTペイロード JSONオブジェクトです。本文に含まれるフィールドは次のセクションを参照してください。
タイムアウト

6秒

HTTPサーバーは受信したPOSTリクエストを6秒未満で受け付ける必要があります。この時間を超えるとFACEIOは接続を自動的に中止します。

WWW-Authenticateヘッダー

この WWW-Authenticate HTTPヘッダーは、FACEIOが開始する各POSTリクエストに必ず含まれます。

各FACEIOアプリケーションに固有

リクエストの真正性を、 Bearer に埋め込まれたトークン値を確認して検証します。 WWW-Authenticate HTTPヘッダーの値は、アプリケーションに割り当てられたトークンキーと一致する必要があります。

このトークンキーは、FACEIO Console ↗のApplication Managerで確認できます。

セキュリティのベストプラクティス

受信したwebhookリクエストは、WWW-Authenticateヘッダーのトークンとアプリケーションのトークンキーを比較して必ず検証してください。不一致を拒否し、イベントを冪等に処理して、セキュリティのベストプラクティスを確認してから、本番の認可フローでwebhookイベントを使用してください。

POSTリクエスト本文

受信したFACEIO webhookリクエストの本文は JSONオブジェクトです。以下のフィールドでイベントを特定し、FACEIOアプリケーションと照合して、アカウント情報を整合させます。

webhook-payload.json 
{
  "eventName": "String - イベント名",
  "facialId": "String - 対象ユーザーの一意な Facial ID",
  "appId": "String - アプリケーションの Public ID",
  "clientIp": "String - パブリック IP アドレス",
  "payload": "Blob - 対象ユーザーに関連付けたデータ（Business Plan 以上で利用可能）",
  "details": {
    "timestamp": "Optional String - イベントのタイムスタンプ",
    "gender": "Optional String - 登録ユーザーの性別",
    "age": "Optional String - 登録ユーザーの年齢"
  }
}

HTTPヘッダー WWW-Authenticateのトークン値をFACEIO Console ↗から取得し、リクエストの真正性を検証します。

eventName このリクエストを発生させたイベント名です。
facialId 対象ユーザーが登録または認証されたときの一意のFacial IDです。
appId このリクエストを発生させたアプリケーションのPublic IDです。各アプリケーションのPublic IDはFACEIO Console ↗で確認できます。
clientIp fio.jsブラウザーセッションの公開IPアドレスです。クライアントIPデータを保存または保持する前に、プライバシーのベストプラクティスを確認してください。
payload 登録時にこのユーザーへ関連付けたデータです。payloadは最小限にし、秘密情報や不要な個人データを保存しないでください。同じデータは、将来の認証時にJavaScriptフロントエンドへ返されます。

payloadフィールドは、アプリケーションがBusiness Plan以上の場合のみWebhookに含まれます。詳しくは料金ページを参照してください。Facial IDの DELETIONイベントには、このフィールドは含まれません。

任意フィールド（登録時のみ）

JSON本文の次のフィールドは、 新規ユーザー登録 イベントに含まれます：

timestamp 操作日時（UTC）をYYYY-MM-DD形式で示します。
gender 登録ユーザーの性別です。値は male または female です。
age 登録ユーザーの推定年齢です。

イベント

Webhookエンドポイントへ送信される各HTTPS POSTリクエストは、次のFACEIOイベントのいずれかによって発生します。JSON POST payloadのeventNameフィールドに対応するキーが入ります。

イベント名 説明
ENROLL ユーザー登録が成功した後に発生します。
AUTH ユーザー認証が成功した後に発生します。
DELETION Facial IDの削除が成功した後に発生します。

実装のヒント

  • タイムアウトを避けるため、webhookエンドポイントが6秒以内に応答することを確認してください。
  • 必ず WWW-Authenticate ヘッダートークンを検証してください。
  • アプリケーションをブロックしないよう、webhookイベントを非同期かつ冪等に処理してください。
  • デバッグ、照合、監査に必要なメタデータだけをログに記録してください。
  • webhookの受信を確認するため、200 OKステータスコードを返してください。
  • イベント後にバックエンドでFacial IDの状態を確認または照合する必要がある場合は、REST APIを使用します。

バックエンド向けにWebhookを設定

FACEIO ConsoleでHTTPS Webhook URLを登録し、サーバーでWebhook tokenを検証して、登録、認証、Facial ID削除イベントをバックエンドで処理します。

統合ガイドを読む → FACEIO Consoleを開く
HTTPSコールバックURL
Webhook tokenの検証
イベント駆動のバックエンド同期