この記事では、Fin ProcedureでWait for Webhookツールを設定し、Finが外部システムの応答を待つ時間を構成し、コールバックが届かない場合のトラブルシューティング方法を説明します。Wait for Webhookツールは、Finが手続きの途中で一時停止し、身元確認プロバイダー（例：Onfido）や支払い・銀行連携（例：Plaid）など非同期でリクエストを処理する外部システムからの入力を待ってから再開します。
注意：
Wait for WebhookはInstructionステップ内でのみ利用可能です。Instructionステップ内で@を入力し、ツールピッカーからWait for Webhookを選択して追加します。
Wait for Webhookを使うタイミング
手続きが外部システムに処理を委ね、その結果を待ってから続行する必要がある場合にこのツールを使用します。外部システムは非同期でリクエストを処理し、即時に応答を返しません。
一般的な使用例は以下の通りです：
身元または年齢確認 — KYC（Know Your Customer）プロバイダーが顧客の身元を確認するのを待つ場合
支払い承認 — 支払い処理業者が取引を確認するのを待つ場合
アカウント連携 — OAuth（オープン認証標準）フローの完了を待つ場合
注文履行チェック — 倉庫システムが在庫の有無を確認するのを待つ場合
承認workflows — 内部チームが返金や例外を承認するのを待つ場合
FinがWait for Webhookツールに到達したときに起こること
Finが手続き内のWait for Webhookツールに到達すると、以下のことが起こります：
手続きの実行が開始されると、Finは各Wait for Webhookツールに対して一意のコールバックURLを生成します。
FinがWait for Webhookツールに到達する前に、Data Connectorを使ってこのコールバックURLを外部システムに渡すよう手続きを設定してください。
外部システムが処理を完了し、WebhookをコールバックURLに送信すると、Finは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を返す場合、両方を応答属性としてここに追加します。
待機時間とフォールバック
Finがコールバックを待つ時間を設定します。タイムアウト時に顧客に送信するエスカレーションメッセージと、会話を割り当てるエスカレーション担当者も設定する必要があります。
重要：サイドパネルでエスカレーションメッセージとエスカレーション担当者の両方を必ず設定してください。どちらかが欠けていると、タイムアウト時の動作が予測できなくなります。
コールバックURLを外部システムに渡す方法
コールバックURLは手続き開始時に生成され、Wait for Webhookツールに到達した時点ではありません。つまり、最初のステップを含む任意の早い段階で外部システムに渡せます。URLを渡すにはData Connectorを使用します。
外部システムのAPI（例：「Start ID Verification」エンドポイント）を呼び出すData Connectorを設定します。
Data ConnectorをコールバックURLを入力パラメーターとして受け取るように設定します。
手続きエディターで、この入力パラメーターをWebhookツールのURL属性にマッピングします。
手続きがWait for Webhookツールに到達する前に、このData Connectorを呼び出すよう設定してください。
FinがData Connectorを呼び出すと、リクエストに一意のコールバックURLが渡されます。外部システムはこのURLを保存し、処理完了後に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は必ずハンドオフします。タイムアウト自体で条件分岐はありません。顧客には設定されたタイムアウトメッセージが最初に表示され、その後会話は設定されたターゲットにハンドオフされます。
エスカレーションメッセージ： タイムアウト時にFinが顧客に送信するメッセージ。
エスカレーション担当者： メッセージ送信後に会話がルーティングされるチームまたは担当者。
ヒント：
待機時間は外部システムの処理時間に合わせて、適切な余裕を持って設定してください。通常10秒で応答するプロバイダーなら、60秒の待機時間が安全なマージンを確保しつつ応答性も保てます。
手続きが設定できたら、Proceduresエディターのシミュレーション機能を使ってWait for Webhookのフローを実際の顧客に届く前にエンドツーエンドで検証してください。シミュレーションでモックのコールバックペイロードを定義し、Finがたどるべき手続き経路に基づいて成功基準を設定します。
重要： PreviewおよびTest Finでは、このステップは実際のWebhookコールバックを待たず、各属性の設定されたデフォルト値を使って即時に解決します。実際の待機・タイムアウト動作をテストするには、シミュレーションを使うか、ワークスペースのライブプレビュ―コールバック有効化についてサポートに問い合わせてください。
Wait for Webhookツールの制限は？
Wait for Webhookツールの現行バージョンには以下の制限があります：
スカラー値のみ： 応答属性はテキストと数値のみ対応。Webhookペイロード内の配列やネストされたJSONオブジェクトは取り込まれません。
大文字小文字を区別する属性名の一致： 応答属性名はWebhookペイロード内の対応するキーと完全に一致する必要があります。名前が一致しない場合、その値は取り込まれずエラーも表示されません。値が空の場合は属性名をよく確認してください。
ループバック時のコールバックURL再利用： 手続きが同じWait for Webhookツールに複数回ループバックする場合、同じコールバックURLが再利用されます。
Workflowsとは別： Fin ProceduresのWait for WebhookツールはWorkflowsのWait for Webhookステップとは別実装です。設定は共有されず再利用できません。
よくある質問
Webhookが届かなかった場合は？
Webhookが届かなかった場合は？
設定された待機時間内にコールバックが受信されない場合、Finはタイムアウトパスをトリガーします。設定されたタイムアウトメッセージを顧客に送信し、設定されたターゲット（チームまたはworkflow）にハンドオフします。手続きは継続せず、ハンドオフ先がworkflowの場合はworkflowが次の動作を決定し、手続きは再開されません。
コールバックURLを外部システムにどう渡す？
コールバックURLを外部システムにどう渡す？
Wait for Webhookツールの前に配置したData Connectorステップを使います。コネクターを外部システムのAPI呼び出しに設定し、Webhookツールのコールバック属性を入力パラメーターとしてマッピングします。Finはコネクター呼び出し時にコールバックURLを外部システムに渡し、システムはコールバック送信先を認識します。
複数の会話で同じコールバックURLを使えますか？
複数の会話で同じコールバックURLを使えますか？
いいえ。コールバックURLは手続きの実行ごとに一意で、手続き開始時に生成されます。Wait for Webhookツールに到達した時点ではありません。顧客ごとに手続きが実行されるたびに新しいURLが生成されます。静的なエンドポイントとして保存したり、複数の会話で再利用したりできません。
外部システムはどのペイロードフィールドを返せますか？
外部システムはどのペイロードフィールドを返せますか？
外部システムはWebhookペイロードに任意のフィールドを含められますが、Wait for Webhookツールの設定で応答属性として定義したフィールドのみFinが取り込み、後続のステップで利用可能です。その他のフィールドは無視されます。
Finがコールバックを待っている間は？
Finがコールバックを待っている間は？
FinはWebhookコールバックを待っている間、顧客からのメッセージに応答しません。会話は実質的に沈黙状態となり、コールバック到着またはタイムアウトまで続きます。
ヒント： Wait for Webhookツールの前に必ずInstructionステップを追加し、顧客に状況を伝えてください。例：「身元確認を行っています。送信したリンクの手続きを完了してください。」これがないと、Finは会話中に説明なしで沈黙します。
Wait for Webhookを使うにはどんな権限が必要？
Wait for Webhookを使うにはどんな権限が必要？
Fin Proceduresの作成・編集（Wait for Webhookツールの追加を含む）にはcan manage workspace data権限が必要です。権限は設定 > ワークスペース > チームメンバーで確認・更新できます。