メインコンテンツへスキップ

セットアップ

IDCloudは、連携方法に応じて2つのWebhookモダリティをサポートしています:

  • Via Portal — WebおよびSDK連携向け。IDCloudポータルでセルフサービス設定が可能です。
  • By client — Checkオーケストレーション機能を使用するAPI連携向け（非同期フロー）。Unicoチームが設定します。ブラジルのみ利用可能です。

Webhookエンドポイントを登録または更新するには、IDCloudポータルにアクセスし、設定 > Webhook に移動してください。

必要な情報​

フィールド説明
通知URLUnicoがイベント通知を配信するために呼び出すエンドポイント。HTTPSでアクセス可能である必要があります。
認証タイプUnicoがエンドポイントに対して認証する方法。以下のオプションを参照してください。
リトライ設定最大試行回数と試行間隔（指数バックオフが適用されます）。
同時実行数制限同時処理中の配信の最大数（最大: 500）。
タイムアウトエンドポイントのレスポンスの最大待機時間（秒単位）。
通知するステータス通知をトリガーするプロセス状態のセット。現在は PROCESS_STATE_FINISHED に固定されており、この時点では設定変更はできません。

認証方法​

OAuth2

提供するもの:

  • Webhookのendpoint
  • OAuth2プロバイダーのURL
  • OAuth2プロバイダーのClientId
  • OAuth2プロバイダーのSecret

Unicoはクライアント認証情報を使用してプロバイダーURLからアクセストークンをリクエストし、Bearerトークンとしてエンドポイントに転送します。

Basic Authorization

user:passの形式で認証情報を提供してください。UnicはBase64でエンコードし、すべてのWebhook呼び出しのAuthorization: Basic <encoded>ヘッダーで送信します。

API Key

2つの形式がサポートされています。文字列は最初のコロンで分割されます:

  • header:value — カスタムヘッダー名を設定します。例:
    • X-API-Key:abc123 → X-API-Key: abc123
    • Authorization:Bearer abc123 → Authorization: Bearer abc123
  • valueのみ（コロンなし） — 値はスキームプレフィックスなしでAuthorizationヘッダーとして送信されます。例: abc123 → Authorization: abc123。

Bearerスキームが必要な場合はheader:value形式を使用してください（例: Authorization:Bearer <token>）。値のみの形式はプレフィックスなしで生の値を送信します。

認証なし

認証情報は送信されません。開発環境のみで推奨されます。本番環境のエンドポイントは常に認証を要求する必要があります。

通知をトリガーするプロセス状態​

現在、Unicoはプロセスが以下の状態に遷移するたびに通知を送信します:

状態説明
PROCESS_STATE_FINISHEDプロセス完了 — 結果に関わらずの終端状態。
状態は変化する可能性があります

プラットフォームから通知される状態のセットは将来変更される可能性があります。エンドポイントが反応する状態を設定可能にしてください。そうすることで、新しい状態を追加する際にサービスの再デプロイが不要になります。

リクエスト形式​

Webhookの配信はエンドポイントへのPOSTリクエストです。ボディにはプロセス識別子と現在の状態が含まれます。

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
lastEvent と lastEventDescription

これら 2 つのフィールドは、result = expired の場合のみ、つまりユーザーがジャーニーを完了する前にプロセスが期限切れになった場合にのみペイロードに表示されます。通常の完了ペイロードには含まれません。完全なスキーマと使用可能な lastEvent 値の一覧については、イベントタイプを参照してください。

期待されるレスポンス​

エンドポイントは同期的にレスポンスを返す必要があります:

  • 成功: 200〜299の範囲内の任意のHTTPステータス。
  • 失敗: その他のステータス。Unicoは設定された最大試行回数まで、または2xxを受信するまで指数バックオフでリトライします。
速やかにレスポンスを返す

設定されたタイムアウト内にWebhookを迅速に確認応答し（アクノリッジ）、ペイロードの処理は自社側で非同期に行ってください。Webhookハンドラー内での長時間の処理は、タイムアウトや不要なリトライの可能性を高めます。

冪等性とリトライ処理のガイダンスについては、セキュリティを参照してください。

最終更新 に