Webhook
Webhookは、本人確認ジャーニーで何かが発生したときに、IDCloudがお客様のシステムへ自動的に通知する仕組みです。お客様のシステムが「もう終わった?」と問い合わせる代わりに、 IDCloudがイベント発生の瞬間にお客様のAPIを呼び出します。
この画面では、お客様のAPIのアドレス、IDCloudがそれに対してどのように認証を行うか、そして応答がなかった場合に何が起きるかを設定します。
対象者: ポーリングを行わずにジャーニーの結果を自動的に受け取りたいお客様。す べての連携タイプに適用されます。
お客様のシステムで変わること: IDCloudをポーリングする必要がなくなり、状態が変化するたびに通知を受け取るようになります。
設定場所: IDCloud Portal → サイドバー Settings → Webhook タブ。
始める前に
アクセス権限
お客様のユーザーには 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 を選択します。5つの選択肢があり、それぞれ異なる フィールドを要求します。
| タイプ | 表示されるフィールド | 使用するタイミング |
|---|---|---|
| None | なし | お客様のAPIが認証を必要としない場合。何らかの別の保護がある場合のみ使用してください——認証がないと、URLを見つけた人が誰でもデータを送信できてしまいます |
| API Key | Secret | お客様のAPIが固定キーを検証する場合 |
| Basic Auth | Secret | お客様のAPIがHTTP Basic方式でユーザー名とパスワードを使用する場合 |
| OAuth 2.0 | Auth URL、Client ID、Secret | お客様のAPIがトークンを要求する場合。IDCloudはそのURLからトークンを取得し、自動的に更新します |
| mTLS | クライアント証明書、秘密鍵、サーバー CA(任意) | お客様のAPIが、証明書を提示するクライアントからの呼び出しのみを受け付ける場合(相互TLS)。IDCloudは、お客様が提供した証明書を通知のたびに提示します |
OAuth 2.0 の場合、Auth URL はIDCloudがトークンを取得するアドレスです——通知を受け取るURLではありません。両者は異なるアドレスであり、それを取り違えることが この画面 で最もよくある間違いです。
Secret は暗号化されて保存されます。既存のWebhookを編集する際、このフィールドは空の状態で表示されます。入力すると現在のシークレットが上書きされ、空のままにすると 既存の値が保持されます。
保存する前に、お客様のAPIを保守する人と認証方式を確認してください。 誤った認証方式を選んでも画面上にエラーは表示されません——後で通知が静かに失敗するようになり、 結果が届かないことで初めて気づくことになります。

Authentication typeフィールドと、それに対応する認証情報フィールド。
mTLSの設定
mTLS では、IDCloudはキー、パスワード、トークンを送信する代わりに、クライアント証明書(相互TLS)を提示することで、お客様のAPIに対して自身を証明します。 お客様のAPIは、その証明書を要求し、発行元を信頼するように設定されている必要があります。mTLS を選択すると、3つのフィールドが表示されます。
| フィールド | 提供する内容 |
|---|---|
| クライアント証明書(PEM) | PEM形式の証明書チェー ン。リーフ証明書を先頭にします。お客様のAPIが信頼している認証局まで証明書チェーンをたどれるように、お客様の証明書の後に中間証明書を追加してください |
| 秘密鍵(PEM) | 証明書と対になる鍵。PEM形式で、パスワードなしのもの。暗号化されて保存され、再表示されることはありません |
| サーバー CA(PEM、任意) | お客様のAPI自身の証明書がプライベート認証局によって署名されている場合のみ。指定しない場合、IDCloudはパブリック認証局を信頼します |
.pemファイルを選択するか、テキストを貼り付けることができます。各フィールドの上限は20,000文字です。
mTLSを選ぶ前に知っておくべきルールがいくつかあります。
- URLはHTTPSである必要があり、お客様のAPIはTLS 1.2以降に対応している必要があります。
- 一度保存すると、認証タイプはロックされます。 この画面では、別の認証タイプに変更できません。認証方式を切り替えるには、Unicoサポートにお問い合わせください。
- 他の認証情報は送信されません。 mTLSは、同じWebhookではAPI Key、Basic Auth、OAuth 2.0と組み合わせることができません。
- リダイレクトは失敗とみなされます。 IDCloudはリダイレクトに従わないため、URLには最終的なアドレスを指定してください。
ステップ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を検証します。mTLSの場合は、代わりに証明書と秘密鍵を検証します。 どちらもPEM形式であること、秘密鍵にパスワードが設定されておらず、証明書と一致していること、そして証明書が有効期間内であることが必要です。
保存後、Your webhook カードにエンドポイントと認証タイプが表示されます。シークレットはマスクされて表示され、画面から取得できなくなります——値を失った場合は、 新しい値を設定する必要があります。
完了とみなす前に、実際のテストを実行してください。 Stagingでジャーニーを開始し、通知がお客様のAPIに届いたことを確認してください。この画面が確認するのは 設定が保存されたことだけであり、お客様のAPIが受信したことではありません。
FAQ
Webhookを複数登録できますか? いいえ。テナントとブランチごとに1つのWebhookです。すでに存在する場合は編集されます——2つ目を作成する方法はありません。
Stagingで設定しました。Productionにも適用されますか? いいえ。環境は独立しています。Staging Portalの設定はUAT用のWebhookを、Production Portalの設定はProduction用を 設定します。Production Portalでも設定を繰り返す必要があります。
登録したシークレットを確認するにはどうすればいいですか? できません。保存時に暗号化され、常にマスクされて表示されます。値を失った場合は、Secretフィールドから 新しい値を登録し てください——入力すると以前の値が上書きされます。
Webhookを編集しましたが、シークレットは変更したくありません。どうすればいいですか? Secretフィールドを空のままにしてください。現在の値が保持されます。
期限が切れる前にmTLSの証明書を置き換えるにはどうすればいいですか? Webhookを編集してください。証明書と秘密鍵はマスクされて表示されます。 新しい証明書と新しい秘密鍵の両方を提供してください——どちらか一方しか変更していない場合でも、両方が必要です。サーバー CAを使用している場合は、それも再度提供してください。 その後、保存してください。IDCloudは約5分以内に新しい証明書の使用を開始するため、以前の証明書は、失効させる前に、それより少し長く有効なままにしておいてください。 3つのフィールドを変更しなければ、現在の証明書が引き続き使用されます。
mTLSから別の認証タイプに切り替えられますか? この画面ではできません。保存後は、認証タイプがロックされるためです。 Webhookの設定を削除するには、Unicoサポートにお問い合わせください。その後、新しい認証方式で作成し直してください。
Webhookを削除するにはどうすればいいですか? この画面には削除機能がありません。設定を削除するには、Unicoサポートにお問い合わせください。目的が通知の受信を 停止することや宛先の変更だけであれば、代わりにURLを編集してください。
保存したのに通知が届きません。 次の順序で確認してください。URLが正しくHTTPSであること、お客様のAPIが稼働していること 、認証方式が期待通りであること、 そしてシークレットが正しく入力されていること。mTLSの場合は、お客様のAPIが証明書の発行元を信頼していること、証明書の有効期限が切れていないこと、 そしてお客様のAPIの証明書がプライベート認証局によるものである場合はサーバー CAが入力されていることも確認してください。 認証の失敗はこの画面上のエラーとして表示されません——配信時に発生します。
「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 | mTLS
│ OAuth 2.0: + Auth URL および Client ID
│ mTLS: + クライアント証明書、秘密鍵、サーバー CA(任意)
└─ 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