この記事では、Wait for WebhookツールをFin手順に追加し、外部システムの応答を待つように設定し、タイムアウトとエスカレーションの動作を構成する方法を説明します。

Wait for WebhookはFin手順を一時停止し、外部システムがwebhookを送信するのを待ちます。webhookは特定のイベント発生時に一方のシステムが他方に送る自動HTTP通知です。Finは会話ごとに固有のコールバックURL（その会話用に生成された専用のウェブアドレス）を持ち、外部システムはこれを使って応答をFinに返します。これにより、身元確認プロバイダー、支払い処理業者、承認システムなど、非同期でリクエストを処理するサードパーティサービスと会話の文脈を失わずに連携できます。

注意：

Wait for Webhookは現在ベータ版です。ワークスペースで有効にするにはサポートチームにアクセスを依頼してください。Fin手順の作成・編集にはcan manage workspace data権限も必要です。

Wait for WebhookはInstructionステップ内でのみ利用可能です。Instructionステップ内で@を入力し、ツールピッカーからWait for Webhookを選択して追加します。

Wait for Webhookを使うタイミング

手順が外部システムに処理を委ね、結果を待ってから続行する必要があり、そのシステムが即時応答ではなく非同期でリクエストを処理する場合にこのツールを使います。

一般的な使用例は以下の通りです：

本人確認や年齢確認 — KYC（Know Your Customer）プロバイダーが顧客の身元を確認するのを待つ
支払い承認 — 支払い処理業者が取引を確認するのを待つ
アカウント連携 — OAuth（オープン認証標準）フローの完了を待つ
注文履行チェック — 倉庫システムが在庫の有無を確認するのを待つ
承認workflows — 内部チームが返金や例外を承認するのを待つ

仕組み

Finが手順内でWait for Webhookツールに到達すると、以下のことが起こります：

Finは手順開始時にこの会話用の固有のコールバックURLを生成します。Wait for Webhookツールに到達した時点ではありません。このURLは手順のどのステップからも利用可能です。
手順は（フロー内で事前に設定されたData Connectorを通じて）このコールバックURLを外部システムに渡します。
外部システムは処理を完了し、応答をコールバックURLに送信します。
Finは応答を受け取り、Wait for Webhookツールの設定で定義された応答属性にペイロードを格納し、次のステップから手順を再開します。
設定された待機時間内にコールバックが受信されない場合、Finはフォールバックアクションをトリガーします。

重要：コールバックURLは手順実行ごとに固有です。複数の会話で再利用したり、静的エンドポイントとして保存したりできません。

Wait for Webhookを手順に追加する方法

エディターで手順を開きます。
Instructionステップ内で@を入力してツールピッカーを開きます。
リストからWait for Webhookを選択します。
Wait for Webhookツールがステップに挿入され、右側に設定サイドパネルが開きます。

ツールの設定方法

Wait for Webhookの設定サイドパネルには3つのフィールドがあります：

ツール名

ツールに説明的な名前を付けます（例：「ID確認コールバック待ち」）。この名前はエディター内でツールを識別し、Data ConnectorでコールバックURLをパラメーターとしてマッピングする際に参照されます。

応答属性

外部システムがwebhookペイロードに含めると予想されるフィールドを定義します。ここで定義した各属性はコールバック到着時にキャプチャされ、後続のステップでRead attributeツールを使って参照できます。

例えば、身元確認プロバイダーがstatusとreference_idを返す場合、両方を応答属性として追加します。

注意：応答属性としてサポートされるのはスカラー文字列値のみです。スカラー値とは単一のテキスト（例：「verified」や「approved」）であり、配列やネストされたJSONオブジェクトではありません。外部システムが複雑なネストペイロードを送る場合は、コールバック前にスカラー値に変換してください。応答属性はwebhook発火前に定義し、手順がライブになってから追加できません。

待機時間とフォールバック

Finがコールバックを待つ時間を設定します。最小・最大待機時間の詳細はIntercomアカウントチームにお問い合わせください。設定された時間内にコールバックがない場合、Finは常に固定ルートでエスカレーションします。Wait for Webhook設定サイドパネルで設定するのは、顧客に送るエスカレーションメッセージと、会話をルーティングするエスカレーション担当者（チームまたはメンバー）です。

重要：サイドパネルでエスカレーションメッセージとエスカレーション担当者の両方を必ず設定してください。どちらかが欠けるとタイムアウト時の動作が予測できなくなります。

コールバックURLを外部システムに渡す方法

コールバックURLは手順開始時に生成されます。Wait for Webhookツールに到達した時ではありません。つまり、最初のステップを含む任意の早い段階で外部システムに渡せます。URLを渡すにはData Connectorを使用します。

外部システムのAPI（例：「Start ID verification」エンドポイント）を呼び出すData Connectorを設定します。
Data Connector設定で入力パラメーターを追加し、webhookツールのコールバック属性にマッピングします。これはこの会話用に動的生成されたコールバックURLです。
Wait for Webhookツールの前にData Connector呼び出しステップを手順に追加します。
FinがData Connectorを呼び出すと、リクエストの一部としてコールバックURLを外部システムに渡します。
外部システムはコールバックURLを保存し、処理完了後に結果をPOSTしてFinに返します。コールバック受信後、FinはWait for Webhookツールから自動的に手順を再開します。

注意：コールバックURLを渡すData ConnectorステップはWait for Webhookツールの前に配置してください。URLは手順開始時から利用可能なので、フローの早い段階で呼び出しても問題ありません。

コールバック後の応答データの読み取り方法

Finがwebhookコールバックを受信して手順を再開すると、応答ペイロードはWait for Webhookツール設定で定義した応答属性に格納されます。後続のInstructionステップでRead attributeツールを使ってこれらの値にアクセスします。

例えば：

verification_statusを読み取り、身元確認が合格か不合格かを確認します。
Conditionステップを使って結果に基づきフローを分岐させます。
応答の値を別のData Connectorに渡してさらに処理します。

Wait for Webhookツールがコールバックを受け取り、キャプチャした応答属性で分岐した後、手順は通常通り次のステップに進みます。設定された待機時間内にコールバックが届かない場合は、下記「待機時間切れ時の動作」の通りFinがエスカレーションします。

待機時間切れ時の動作は？

Wait for Webhookツールの設定待機時間内にコールバックが受信されない場合、Finは必ずエスカレーションします。条件分岐はなく、タイムアウトによる異なる動作設定はできません。エスカレーションは常に以下の2ステップで行われます：

エスカレーションメッセージ：タイムアウト時にFinが顧客に送るメッセージ。
エスカレーション担当者：メッセージ送信後に会話がルーティングされるチームまたはメンバー。

ヒント：

外部システムの処理時間に合わせて待機時間を設定し、適切な余裕を持たせましょう。通常10秒で応答する場合、60秒の待機時間は安全なマージンを確保しつつ応答性も保てます。

手順設定後、Proceduresエディターのシミュレーション機能でWait for Webhookのフローを実際の顧客に届く前に検証します。シミュレーションでモックコールバックペイロードを定義し、Finがたどるべき手順パスに基づいて成功基準を設定します。

よくある質問

私のwebhookが届きませんでした—どうなりますか？

設定された待機時間内にコールバックが受信されない場合、Finはエスカレーションパスをトリガーします。設定されたエスカレーションメッセージを顧客に送り、会話をエスカレーション担当者にルーティングします。手順は続行しません。

コールバックURLを外部システムにどう渡しますか？

手順内でWait for Webhookツールの前にData Connectorステップを配置します。コネクターを設定して外部システムのAPIを呼び出し、webhookツールのコールバック属性を入力パラメーターとしてマッピングします。Finはコネクター呼び出し時にコールバックURLを外部システムに渡し、システムはコールバック送信先を認識します。