Use this article to add the Wait for Webhook tool to a Fin Procedure, configure it to pause and wait for an external system's response, and set up timeout and escalation behavior.
Wait for Webhook pauses a Fin Procedure and waits for an external system to send a webhook, an automated HTTP notification that one system sends to another when a specific event occurs, before Fin resumes. Each conversation gets a unique callback URL (a dedicated web address that Fin generates for that conversation), which your external system uses to send its response back to Fin. This makes it possible to integrate with third-party services that process requests asynchronously — such as identity verification providers, payment processors, or approval systems — without losing the context of the ongoing conversation.
Note:
Wait for Webhook is currently in beta. To enable it for your workspace, contact the support team to request access. You'll also need the can manage workspace data permission to create or edit Fin Procedures.
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
How it works
When Fin reaches a Wait for Webhook tool in a procedure, the following happens:
Fin generates a unique callback URL for this conversation when the procedure starts — not when execution reaches the Wait for Webhook tool. This URL is available to any step in the procedure from the very beginning.
Your procedure (via a Data Connector configured earlier in the flow) passes this callback URL to your external system.
The external system completes its processing and sends its response to the callback URL.
Fin receives the response, captures the payload into the response attributes defined in the Wait for Webhook tool configuration, and resumes the procedure from the next step.
If no callback is received within the configured wait time, Fin triggers the fallback action.
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.
Note: Only scalar string values are supported as response attributes — a scalar value is a single piece of text (for example, "verified" or "approved"), as opposed to arrays or nested JSON objects. If your external system sends a complex nested payload, transform it into scalar values before sending the callback. Response attributes must be defined before the webhook fires and cannot be added retroactively once the procedure is live.
Wait time and fallback
Set how long Fin should wait for a callback before escalating. Contact your Intercom account team for details on minimum and maximum wait time values. If no callback is received within the configured window, Fin always escalates via a fixed path — there is no conditional branching on timeout. You must configure two things in the Wait for Webhook configuration side panel: an escalation message to send the customer, and an escalation assignee (a team or teammate) to route the conversation to.
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 (for example, a "Start ID verification" endpoint).
In the Data Connector configuration, add an input parameter and map it to the webhook tool callback attribute — this is the dynamically generated callback URL for this conversation.
Add a Call data connector step in your procedure before the Wait for Webhook tool.
When Fin calls the Data Connector, it passes the callback URL to your external system as part of the request.
Your external system stores the callback URL and uses it to POST the result back to Fin once processing is complete. Once the callback is received, Fin resumes the procedure automatically from the Wait for Webhook tool.
Note: The Data Connector step that passes the callback URL must come before the Wait for Webhook tool. Since the URL is available from the moment the procedure starts, your connector call can be as early in the flow as you need.
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 escalates. There is no conditional branching — you cannot configure different behavior depending on the timeout. The escalation always follows these two steps:
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.
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 escalation path — it sends the configured escalation message to the customer and routes the conversation to the escalation assignee. The procedure does not continue.
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.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts