Use this article to set up the Wait for Webhook tool in a Fin Procedure, configure how long Fin waits for an external system's response, and troubleshoot what happens if a callback never arrives. The Wait for Webhook tool pauses Fin mid-procedure so it can wait for external input from systems that process requests asynchronously, such as identity verification providers (e.g. Onfido) or payment and banking integrations (e.g. Plaid), before resuming.
Note:
Wait for Webhook is only available inside Instruction steps. Add it by typing @ inside an Instruction step and selecting Wait for Webhook from the tool picker.
When to use Wait for Webhook
Use this tool when your procedure needs to hand off to an external system and wait for a result before continuing — and that system processes requests asynchronously rather than returning a response immediately.
Common use cases include:
Identity or age verification — waiting for a KYC (Know Your Customer) provider to confirm a customer's identity
Payment authorization — waiting for a payment processor to confirm a transaction
Account linking — waiting for an OAuth (open authorization standard) flow to complete
Order fulfillment checks — waiting for a warehouse system to confirm stock availability
Approval workflows — waiting for an internal team to approve a refund or exception
What happens when Fin reaches the Wait for Webhook tool
When Fin reaches a Wait for Webhook tool in a procedure, the following happens:
When a procedure run starts, Fin generates a unique callback URL for each Wait for Webhook tool.
Configure your procedure to pass this callback URL to your external system using a Data Connector before Fin reaches the Wait for Webhook tool.
Once the external system completes its processing and sends a webhook to the callback URL, Fin captures the webhook payload into the configured response attributes and resumes the procedure automatically.
If no callback is received within the configured wait time, Fin sends the configured escalation message and assigns the conversation to the configured escalation assignee.
Important: The callback URL is unique per procedure run. It cannot be reused across multiple conversations or stored as a static endpoint.
How to add Wait for Webhook to a procedure
Open your procedure in the editor.
Inside an Instruction step, type @ to open the tool picker.
Select Wait for Webhook from the list.
The Wait for Webhook tool is inserted into the step and a configuration side panel opens on the right.
How to configure the tool
The Wait for Webhook configuration side panel has three fields:
Tool name
Give the tool a descriptive name (for example, "Wait for ID verification callback"). This name identifies the tool in the editor and is referenced when you map the callback URL as a parameter in your Data Connector.
Response attributes
Define the fields you expect the external system to include in its webhook payload. Each attribute defined here is captured when the callback arrives and can be referenced in later steps using the Read attribute tool.
For example, if your identity verification provider sends back a status and a reference_id, add both as response attributes here.
Wait time and fallback
Set how long Fin should wait for a callback before escalating. You must also configure the escalation message sent to the customer and select the assignee to whom the conversation will be routed if the timeout is reached.
Important: Always configure both an escalation message and an escalation assignee in the side panel. If either is missing, the timeout behavior may be unpredictable.
How to pass the callback URL to your external system
The callback URL is generated when the procedure starts — not when execution reaches the Wait for Webhook tool. This means you can pass it to your external system at any earlier step, including the very first step. To pass the URL, use a Data Connector.
Set up a Data Connector that calls your external system's API (e.g., a "Start ID Verification" endpoint).
Configure the Data Connector to accept a callback URL as an input parameter.
In the procedure editor, map this input parameter to the webhook tool's URL attribute.
Ensure the procedure is set up to call this Data Connector before it reaches the Wait for Webhook tool.
When Fin calls the Data Connector, it passes the unique callback URL in the request. Your external system stores this URL and sends the webhook callback to it once processing is complete.
Note: Call to the data connector that passes the callback URL must happen before the Wait for Webhook tool. This allows the external system to get access to the callback url.
How to read response data after the callback
Once Fin receives the webhook callback and resumes the procedure, the response payload is captured in the response attributes you defined in the Wait for Webhook tool configuration. Use the Read attribute tool in a subsequent Instruction step to access these values.
For example:
Read verification_status to check whether the identity check passed or failed.
Use a Condition step to branch the flow based on the result.
Pass values from the response to another Data Connector for further processing.
Once the Wait for Webhook tool has received its callback and you've branched on the captured response attributes, the procedure continues to its next step normally. If the callback never arrives within the configured wait time, Fin escalates as described in 'What happens when the wait times out?' below.
What happens when the wait times out?
When the Wait for Webhook tool's configured wait time expires without receiving a callback, Fin always hands off — there is no conditional branching on the timeout itself. The customer sees the configured timeout message first, then the conversation hands off to the configured target:
Escalation message: The message Fin sends to the customer when the timeout fires.
Escalation assignee: The team or teammate the conversation is routed to after the message is sent.
Tip:
Set your wait time to match the expected processing time of your external system, with a reasonable buffer. If your provider typically responds in 10 seconds, a 60-second wait time gives a safe margin while keeping the experience responsive.
Once your procedure is set up, use Simulations in the Procedures editor to validate the Wait for Webhook flow end-to-end before it reaches real customers. Define a mock callback payload in the simulation and set success criteria based on the procedure path you expect Fin to follow.
Important: In Preview and Test Fin, this step does not wait for a real webhook callback — it resolves immediately using each attribute's configured default value. To test the real wait/timeout behavior, use Simulations or contact support about enabling live preview callbacks for your workspace.
What are the limitations of the Wait for Webhook tool?
The Wait for Webhook tool has the following limitations in its current version:
Scalar values only: Response attributes support text and number values only. Arrays and nested JSON objects in the webhook payload aren't captured.
Case-sensitive attribute matching: A response attribute's name must exactly match the corresponding key in the webhook payload. If the names don't match, that value isn't captured — and no error is shown, so check attribute names carefully if a value comes back empty.
Callback URL reuse on loop-back: If a procedure loops back to the same Wait for Webhook tool more than once in a single run, the same callback URL is reused for that tool.
Separate from Workflows: The Wait for Webhook tool in Fin Procedures is a separate implementation from the Wait for Webhook step in Workflows. Configuration isn't shared or reusable between the two.
FAQs
My webhook never arrived — what happens?
My webhook never arrived — what happens?
If no callback is received within the configured wait time, Fin triggers the timeout path — it sends the configured timeout message to the customer and hands off to the configured target, which can be a team or a workflow. The procedure does not continue; if the handoff is to a workflow, the workflow decides what happens next and the procedure does not pick up again.
How do I get the callback URL to my external system?
How do I get the callback URL to my external system?
Use a Data Connector step placed before the Wait for Webhook tool in your procedure. Configure the connector to call your external system's API and map the webhook tool callback attribute as an input parameter. Fin passes the callback URL to the external system when the connector is called, so the system knows where to send the callback.
Can I use the same callback URL for multiple conversations?
Can I use the same callback URL for multiple conversations?
No. The callback URL is unique per procedure run and is generated when the procedure starts — not when execution reaches the Wait for Webhook tool. Each time a procedure runs for a customer, a new URL is generated. You cannot store it as a static endpoint or reuse it across conversations.
What payload fields can my external system send back?
What payload fields can my external system send back?
Your external system can include any fields in the webhook payload, but only the fields you've defined as response attributes in the Wait for Webhook tool configuration are captured by Fin and available in subsequent steps. Any additional fields in the payload are ignored.
What happens while Fin is waiting for a callback?
What happens while Fin is waiting for a callback?
While Fin is paused waiting for a webhook callback, it does not respond to incoming customer messages. The conversation is effectively silent until the callback arrives or the timeout fires.
Tip: Always add an Instruction step before the Wait for Webhook tool to tell the customer what’s happening — for example, “We’re verifying your identity. Please complete the step in the link we’ve sent you.” Without this, Fin will go silent mid-conversation with no explanation to the customer.
What permissions do I need to use Wait for Webhook?
What permissions do I need to use Wait for Webhook?
You need the can manage workspace data permission to create or edit Fin Procedures, including adding the Wait for Webhook tool. You can check and update permissions in Settings > Workspace > Teammates.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts