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

Fin ProceduresでWait for Webhookツールを使う方法

Wait for Webhookツールを使って、Fin Procedureの途中で処理を一時停止し、外部システムからのコールバックを受けて再開する方法を学びます。身元確認、支払い、承認などの非同期連携に最適です。

対応者：Dawn

Wait for Webhookツールは、Finが手続きの途中で一時停止し、外部からの入力を待つことを可能にします。OnfidoやPlaidなどのサードパーティシステムとの連携が必要なプロセスを自動化し、非同期処理を実現します。

注意：

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

    Wait for Webhookを使うタイミング

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

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

    • 本人確認や年齢確認 — KYC（Know Your Customer）プロバイダーが顧客の身元を確認するのを待つ場合

    • 支払い承認 — 支払い処理業者が取引を確認するのを待つ場合

    • アカウント連携 — OAuth（オープン認証標準）フローの完了を待つ場合

    • 注文履行チェック — 倉庫システムが在庫の有無を確認するのを待つ場合

    • 承認ワークフロー — 返金や例外の承認を内部チームが行うのを待つ場合

    仕組み

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

    1. 手続きの実行が始まると、Finは各Wait for Webhookツールに対して一意のコールバックURLを生成します。

    2. FinがWait for Webhookツールに到達する前に、Data Connectorを使ってこのコールバックURLを外部システムに渡すよう手続きを設定します。

    3. 外部システムが処理を完了し、WebhookをコールバックURLに送信すると、FinはWebhookのペイロードを設定された応答属性に取り込み、自動的に手続きを再開します。

    4. 設定された待機時間内にコールバックが受信されない場合、Finは設定されたエスカレーションメッセージを送信し、会話を設定されたエスカレーション担当者に割り当てます。

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

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

    1. エディターで手続きを開きます。

    2. Instructionステップ内で@を入力してツールピッカーを開きます。

    3. リストからWait for Webhookを選択します。

    4. Wait for Webhookツールがステップに挿入され、右側に設定サイドパネルが開きます。

    ツールの設定方法

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

    ツール名

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

    応答属性

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

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

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

    Finがコールバックを待つ時間を設定します。タイムアウト時に送信するエスカレーションメッセージと、会話を割り当てるエスカレーション担当者も設定する必要があります。

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

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

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

    1. 外部システムのAPI（例：「Start ID Verification」エンドポイント）を呼び出すData Connectorを設定します。

    2. Data ConnectorをコールバックURLを入力パラメーターとして受け取るよう設定します。

    3. 手続きエディターで、この入力パラメーターをWebhookツールのURL属性にマッピングします。

    4. 手続きがWait for Webhookツールに到達する前に、このData Connectorを呼び出すよう設定されていることを確認してください。

    5. 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は必ずエスカレーションします。条件分岐はなく、タイムアウト時の動作を変えることはできません。エスカレーションは常に以下の2ステップで行われます:

    1. エスカレーションメッセージ： タイムアウト時にFinが顧客に送信するメッセージ。

    2. エスカレーション担当者： メッセージ送信後に会話がルーティングされるチームまたは担当者。

    ヒント：

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

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

    重要： PreviewおよびTest Finでは、このステップは実際のWebhookコールバックを待たず、各属性の設定されたデフォルト値で即時に解決します。実際の待機・タイムアウト動作をテストするには、シミュレーションを使うか、ワークスペースのライブプレビュ―コールバック有効化についてサポートに問い合わせてください。

    よくある質問

    Webhookが届かない場合は？

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

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

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

    複数の会話で同じコールバックURLを使えますか？

    いいえ。コールバックURLは手続き実行ごとに一意で、手続き開始時に生成されます。Wait for Webhookツールに到達した時点ではありません。顧客ごとに手続きが実行されるたびに新しいURLが生成されます。静的なエンドポイントとして保存したり、会話間で再利用したりできません。

    外部システムはどのペイロードフィールドを返せますか？

    外部システムはWebhookペイロードに任意のフィールドを含められますが、Wait for Webhookツールの設定で応答属性として定義したフィールドのみがFinにキャプチャされ、後続ステップで利用可能です。追加のフィールドは無視されます。

    Finがコールバックを待っている間は？

    FinはWebhookコールバックを待機中は顧客からのメッセージに応答しません。コールバック到着またはタイムアウトまで会話は実質的に沈黙します。

    ヒント： Wait for Webhookツールの前に必ずInstructionステップを追加し、顧客に状況を伝えましょう。例えば「本人確認を行っています。送信したリンクの手続きを完了してください。」これがないと、Finは会話の途中で説明なく沈黙します。

    Wait for Webhookを使うにはどんな権限が必要？

    Fin Proceduresの作成や編集、Wait for Webhookツールの追加にはcan manage workspace data権限が必要です。権限は設定 > ワークスペース > チームメンバーで確認・更新できます。

    関連記事
    こちらの回答で解決しましたか？