The Respond by API channel lets you connect Human-in-the-Loop (HITL) steps in Fin Procedures to your own systems using webhooks and the Intercom API. When Fin reaches a HITL step, Intercom sends a webhook to your endpoint. Your system processes the request, fills in the required attributes, and sends a response back, allowing the procedure to continue automatically.
Note: This feature is currently in managed availability. To use it, your Developer Hub app must be set to the Preview API version.
Examples
Here are some ways you can use this feature:
Automated approval workflows: Route refund or discount approvals to an internal tool that applies business rules and responds automatically
Custom teammate dashboards: Surface HITL requests in your own support tooling or internal portal alongside other tasks
Escalation to external teams: Forward questions to teams that don't use Intercom — such as engineering, legal, or finance — and capture their response
Audit and compliance logging: Log every HITL decision to a compliance system before responding, creating an automatic paper trail
Before you begin
To set up Respond by API, you'll need:
A Fin Procedure with at least one Human-in-the-Loop step
A Developer Hub app — create one in Settings > Developer Hub if you don't have one yet
An HTTPS endpoint that can receive webhook requests
Your Developer Hub app must have the read_conversations and write_conversations OAuth scopes
Step 1: Enable Ask via webhook in your procedure
Open the procedure you want to configure in the Procedures editor.
Select your Human-in-the-Loop step.
Open the step's Settings panel by clicking the gear icon.
Select the More channels tab.
Expand the Ask via webhook section.
Toggle Enable for this procedure to on.
Click Verify webhook setup to confirm your Developer Hub app is correctly subscribed.
Save your procedure.
After clicking Verify webhook setup, you'll see one of:
"Webhook connected." — your webhook is set up correctly
"No webhook found." — you need to configure your webhook in Developer Hub (see Step 2)
If verification fails, click Developer Hub to open your app's configuration in a new tab.
Note: The Ask via webhook channel works alongside the Inbox and Slack channels. When a HITL step is reached, all enabled channels are notified at the same time. Whichever channel responds first wins — subsequent responses are rejected.
Step 2: Configure your webhook in Developer Hub
Go to Settings > Developer Hub, or navigate directly to your app settings.
Select your app, or create a new one.
Go to API Version and switch to Preview.
Go to Webhooks in your app's configuration.
Enter your webhook endpoint URL (must be HTTPS).
Add the procedure.hitl_notification.created topic to your subscribed topics.
Ensure your app has the required OAuth scopes: read_conversations (required to receive webhook notifications) and write_conversations (required to send callback responses via the API).
Save your webhook configuration.
Important: The HITL webhook topic is only available on the Preview API version while this feature is in managed availability. You must switch to this version before the topic will appear in the webhook topics list.
Step 3: Handle the webhook payload
When a procedure reaches a Human-in-the-Loop step with Ask via webhook enabled, Intercom sends a POST request to your webhook endpoint. The payload includes:
The conversation ID
The question Fin is asking
The attributes your system needs to fill in
A callback URL to send your response to
Recent conversation messages for context
For full payload and field specifications, see the procedures API reference.
Step 4: Send a callback response
Once your system has processed the HITL request, send a POST request to the callback_url provided in the webhook payload. Include the step_id and the values for each attribute listed in attributes_to_collect. Authenticate with a Bearer token that has the write_conversations OAuth scope.
After a successful response, Fin resumes the procedure using the attribute values you provided. The teammate associated with your OAuth token is recorded as the one who responded.
For the full callback request format, authentication details, supported data types, and error codes, see the procedures API reference.
Best practices
Keep these in mind when building your integration:
Verify webhook signatures: Intercom signs webhook payloads with HMAC. Always verify the signature to confirm the request is authentic. See the procedures API reference for details.
Respond before the timeout: HITL requests have a configurable wait time set in the Procedures editor. If no response is received before expires_at, the procedure runs its configured timeout behavior (escalation message, reassignment, etc.).
Don't submit duplicate responses: The callback is not idempotent. If you submit a response more than once for the same step, subsequent requests return 409 Conflict. If you receive a 409, your original response was already processed.
For list attributes, send the option id: Don't send the option's display label — send its id from the options array.
Track who responds: The teammate associated with your OAuth token is recorded as the responder. Consider using a dedicated service account if you want a consistent identity.
Handle multi-channel races gracefully: If the API channel is enabled alongside Inbox or Slack, the first response wins. Your system may receive a 409 if a teammate responds through another channel first.
Need more help? Get support from our Community Forum
Find answers and get help from Intercom Support and Community Experts