Webhook
Webhookは、本人確認ジャーニーで何かが発生したときに、IDCloudがお客様のシステムへ自動的に通知する仕組みです。お客様のシステムが「もう終わった?」と問い合わせる代わりに、 IDCloudがイベント発生の瞬間にお客様のAPIを呼び出します。
この画面では、お客様のAPIのアドレス、IDCloudがそれに対してどのように認証を行うか、そして応答がなかった場合に何が起きるかを設定します。
対象者: ポーリングを行わずにジャーニーの結果を自動的に受け取りたいお客様。byUnicoとbyClientの両方のインテグレーションに適用されます。
お客様のシステムで変わること: IDCloudをポーリングする必要がなくなり、状態が変化するたびに通知を受け取るようになります。
設定場所: IDCloud Portal → サイドバー Settings → Webhook タブ。
この画面が存在する前は、Webhookの変更が必要になるたびにサポートチケットが必要でした——それだけで月に約30件のチケットが発生していました。現在は、Staging・Productionの両方で、 自分自身で数分のうちに設定できます。
始める前に
アクセス権限
お客様のユーザーには Configurator プロファイルが必要です——これはJourney Customizationへのアクセスを許可するものと同じプロファイルです。Webhookタブが表示されない場合は、 アカウント管理者にお問い合わせください。
設定の適用方法
| スコープ | テナントとブランチごとに1つのWebhook。一覧はありません。すでに設定済みの場合、複製ではなく編集されます。 |
| 環境の分離 | Staging Portalの設定はUAT用のWebhookを、Production Portalの設定はProduction用を設定します。一方を設定してももう一方には影響しません。 |
| 反映タイミング | 保存した瞬間から。 |
| シークレットのセキュリティ | シークレットは暗号化され、平文で再表示されることはありません。画面上では常にマスクされます。 |
あらかじめ用意しておくもの
- 通知を受け取るお客様のAPIの HTTPS URL。保存する前に、稼働してリクエストを受け付けられる状態になっている必要があります。
- 選択する認証方法に応じて、お客様のAPIが要求する 認証情報(ステップ3を参照)。
- お客様のAPIに処理能力の上限がある場合、対応可能な 1秒あたりのリクエスト数。
あらかじめ決めておくべきこと
2つの技術的な判断は、Portalを操作する人ではなく、お客様のAPIを保守する人に依存します。画面を開く前に合意しておく価値があります。
- お客様のAPIが要求する どの認証方式 を使うか。
- リトライを調整するか、それともデフォルトのままにするか。デフォルトはほとんどのケースで機能します。
手順
ステップ1 — Webhookタブを開く
IDCloud Portalで、サイドバーの ギアアイコン(Settings) をクリックし、Webhook タブを選択します。
まだWebhookが設定されていない場合、画面には 「No webhooks created」 と Create webhook ボタンが表示されます。すでに1つ設定されている場合は、エンドポイント・認証タイプ・ マスクされたシークレットを含む Your webhook カードと、編集用の Configure webhook ボタンが表示されます。
エンドポイント、認証タイプ、マスクされたシークレットを含む「Your webhook」カード。
ステップ2 — お客様のAPIのURLを入力する
Create webhook(すでに存在する場合は Configure webhook)をクリックし、「Client information」の下にある Client URL (Endpoint) フィールドに入力します。
これは、IDCloudが通知を送信するアドレスです。HTTPS である必要があります。
すでに稼働しているアドレスを指定してください。 保存すると同時に、IDCloudはこのURLの呼び出しを開始します。まだ存在しない場合、最初の通知が失敗し、チームが気づく前に リトライを使い果たしてしまいます。
HTTPS要件についてのヘルパーテキストが付いたエンドポイントフィールド。
ステップ3 — IDCloudがお客様のAPIに対して認証する方法を選ぶ
「Authentication」の下で、Authentication type を選択します。4つの選択肢があり、それぞれ異なるフィールドを要求します。
| タイプ | 表示されるフィールド | 使用するタイミング |
|---|---|---|
| None | なし | お客様のAPIが認証を必要としない場合。何らかの別の保護がある場合のみ使用してください——認証がないと、URLを見つけた人が誰でもデータを送信できてしまいます |
| API Key | Secret | お客様のAPIが固定キーを検証する場合 |
| Basic Auth | Secret | お客様のAPIがHTTP Basic方式でユーザー名とパスワードを使用する場合 |
| OAuth 2.0 | Auth URL、Client ID、Secret | お客様のAPIがトークンを要求する場合。IDCloudはそのURLからトークンを取得し、自動的に更新します |
OAuth 2.0 の場合、Auth URL はIDCloudがトークンを取得するアドレスです——通知を受け取るURLではありません。両者は異なるアドレスであり、それを取り違えることが この画面で最もよくある間違いです。
Secret は暗号化されて保存されます。既存のWebhookを編集する際、このフィールドは空の状態で表示されます。入力すると現在のシークレットが上書きされ、空のままにすると 既存の値が保持されます。
保存する前に、お客様のAPIを保守する人と認証方式を確認してください。 誤った認証方式を選んでも画面上にエラーは表示されません——後で通知が静かに失敗するようになり、 結果が届かないことで初めて気づくことになります。
Authentication typeフィールドと、それに対応する認証情報フィールド。
ステップ4 — 必要に応じてリトライを調整する
Retry configuration セクションは オプション で、デフォルトではオフになっています。デフォルトの動作を変更する必要がある場合のみオンにしてください。
オンにすると、6つのフィールドが表示されます。
| フィールド | 制御する内容 | デフォルト |
|---|---|---|
| Maximum retries | 諦め るまでにIDCloudが再試行する回数 | — |
| Rate limit (req/s) | 1秒あたりの最大通知数。お客様のAPIの処理能力に制限がある場合は下げてください | — |
| Minimum time (s) | 試行間の最小間隔 | 2秒 |
| Maximum time (s) | 試行間の最大間隔 | 10秒 |
| Maximum duration (s) | 失敗と判断する前に1回の試行を待つ時間 | 2秒 |
| Maximum doublings | 試行間隔の増加率(バックオフ) | 5 |
組み合わさった動作は次のとおりです。IDCloudは試行し、最小時間 だけ待って再試行し、最大doublings に従って間隔を増やしながら 最大時間 まで到達し——最大リトライ数 に達するまでこれを繰り返します。個々の試行はそれぞれ 最大duration の後に諦めます。
他の項目に触れる前に、まずRate limitを調整してください。 お客様のAPIが負荷でダウンする場合、問題はリトライではなくスループットです——その状況でリトライを増やすと、 呼び出しの数が増えることでむしろ悪化します。まずはレートを下げてください。
Maximum retriesを増やすことは、安定したAPIの代わりにはなりません。 リトライは一時的な 利用不可状態をカバーするものです。お客様のAPIが頻繁に失敗する場合、 この設定は通知を失うタイミングを遅らせるだけです。
トグルをオンにした後に表示される6つのリトライフィールド。
ステップ5 — 保存する
Save をクリックします。Cancel はすべての変更を破棄し、以前の設定を維持します。
認証方式がOAuth 2.0の場合、IDCloudは保存を許可する前にトークンURLを検証します。
保存後、Your webhook カードにエンドポイントと認証タイプが表示されます。シークレットはマスクされて表示され、画面から取得できなくなります——値を失った場合は、 新しい値を設定する必要があります。
完了とみなす前に、実際のテストを実行してください。 Stagingでジャーニーを開始し、通知がお客様のAPIに届いたことを確認してください。この画面が確認するのは 設定が保存されたことだけであり、お客様のAPIが受信したことではありません。
FAQ
Webhookを複数登録できますか? い いえ。テナントとブランチごとに1つのWebhookです。すでに存在する場合は編集されます——2つ目を作成する方法はありません。
Stagingで設定しました。Productionにも適用されますか? いいえ。環境は独立しています。Staging Portalの設定はUAT用のWebhookを、Production Portalの設定はProduction用を 設定します。Production Portalでも設定を繰り返す必要があります。
登録したシークレットを確認するにはどうすればいいですか? できません。保存時に暗号化され、常にマスクされて表示されます。値を失った場合は、Secretフィールドから 新しい値を登録してください——入力すると以前の値が上書きされます。
Webhookを編集しましたが、シークレットは変更したくありません。どうすればいいですか? Secretフィールドを空のままにしてください。現在の値が保持されます。
Webhookを削除するにはどうすればいいですか? この画面には削除機能がありません。設定を削除するには、Unicoサポートにお問い合わせください。目的が通知の受信を 停止することや宛先の変更だけであれば、代わりにURLを編集してください。
保存したのに通知が届きません。 次の順序で確認してください。URLが正しくHTTPSであること、お客様のAPIが稼働していること、認証方式が期待通りであること、 そしてシークレットが正しく入力されていること。認証の失敗はこの画面上のエラーとして表示されません——配信時に発生します。
「Maximum duration」と「Maximum time」の違いは何ですか? 「Maximum time」は2回の試行 間 の最長間隔です。「Maximum duration」は、失敗と判断する前に IDCloudが1回の試行に対して待つ時間です。
すでにAPIで結果をポーリングしている場合、Webhookは必要ですか? 必須ではありませんが、システムがポーリングする必要がなくなります。すでに動作している ポーリングの仕組みがある場合、Webhookは要件ではなく最適化です。
クイックリファレンス
IDCloud Portal
└─ Settings (サイドバーのギアアイコン)
└─ Webhook タブ
├─ Client information ....... Client URL (Endpoint)、HTTPS
├─ Authentication ............ None | API Key | Basic Auth | OAuth 2.0
│ OAuth 2.0: + Auth URL および Client ID
└─ Retries (オプション) ....... Maximum retries
Rate limit (req/s)
Minimum time (2秒) · Maximum time (10秒)
Maximum duration (2秒) · Maximum doublings (5)
テナントとブランチごとに1つのWebhook · UATとProductionは独立 · シークレットは表示されない · Cancel · Save