Skip to main content

​
Overview

Iterable can trigger Clerk Chat AI Agents by sending HTTP requests to an Agent Webhook. When a user reaches a step in an Iterable Journey — or when a system event fires — Iterable POSTs to your agent webhook URL with user and event data. The agent then runs with that context.
This page covers inbound Agent Webhooks (Iterable → Clerk Chat agent). For outbound event webhooks where Clerk Chat notifies your app, see Webhooks.

​
Prerequisites

Before connecting Iterable, complete the generic Agent Webhook setup:
  1. Add a Webhook trigger to your agent and copy the webhook URL — see Trigger an Agent with a Webhook.
  2. Generate a team API key from Settings → API.
  3. Connect your agent to an inbox and deploy it.
You will need:
  • Your Agent Webhook URL: https://web-api.clerk.chat/public/pipelines/webhook/{webhookId}
  • Your Clerk Chat API key
Journey webhooks are the most flexible option. They let you send custom JSON payloads at specific steps in an Iterable Journey, which is ideal for triggering personalized agent conversations.

​
1. Create a Journey webhook in Iterable

  1. In Iterable, go to Integrations → Journey Webhooks.
  2. Click New Webhook (or Create Journey Webhook).
  3. Configure the webhook:
SettingValue
NameA descriptive label (e.g. Clerk Chat Agent Trigger)
HTTP methodPOST
EndpointYour Agent Webhook URL from the Clerk Chat agent builder
AuthenticationCustom HTTP headers
  1. Under Custom HTTP headers, add:
Header nameHeader value
apiKeyYour Clerk Chat API key
  1. Set the request body to JSON. Include phone plus any fields you want the agent to use:
{
  "phone": "{{phoneNumber}}",
  "email": "{{email}}",
  "firstName": "{{firstName}}",
  "campaignId": "{{campaignId}}",
  "journeyName": "{{workflowName}}"
}
Use Iterable’s merge parameters (e.g. {{phoneNumber}}, {{email}}) to populate fields from the user’s profile. The exact parameter names depend on your Iterable project — check your user profile fields and journey context variables.
Always include a phone field when possible. Clerk Chat uses it to find or create a contact and route the conversation to the correct inbox. Without phone, the agent may still run but won’t be associated with a specific contact.
  1. Save the Journey webhook.

​
2. Add the webhook to a Journey

  1. Open the Journey where you want to trigger the agent.
  2. Add a Webhook tile at the step where the agent should run.
  3. Select the Journey webhook you created above.
  4. Save and publish the Journey.
When a user reaches that tile, Iterable sends a POST to your Agent Webhook URL and the Clerk Chat agent runs.

​
Alternative: System webhooks

System webhooks fire automatically when specific project-wide events occur (e.g. email send, email open, list subscribe). Use these when you want an agent to react to Iterable events without building a Journey.

​
1. Create a System webhook in Iterable

  1. Go to Integrations → System Webhooks.
  2. Click Create (or New Webhook).
  3. Configure:
SettingValue
Endpoint URLYour Agent Webhook URL
StatusEnabled
AuthenticationNone (use custom headers instead)
Custom HTTP headersapiKey: YOUR_CLERK_CHAT_API_KEY
Triggering eventsSelect the events that should trigger your agent
System webhooks send Iterable’s standard event payload. You cannot fully customize the body like you can with Journey webhooks. If you need a specific payload shape, use a Journey webhook instead.
  1. Save and enable the webhook.
Iterable’s system webhook payloads include fields like email, phoneNumber, and event metadata. Map the fields your agent needs from webhookBody (see below).

​
Use Iterable data in your agent

Whatever Iterable sends in the request body is available on the trigger node as webhookBody. Reference fields in downstream nodes using: 
{triggerStaticId}.webhookBody.{fieldName}

​
Example

If your Journey webhook sends: 
{
  "phone": "+15551234567",
  "firstName": "Jane",
  "campaignId": "winback-q2",
  "offerCode": "SAVE20"
}
And your trigger node has static ID 1, reference fields like this:
Iterable fieldAgent variable pathTemplate example
phone1.webhookBody.phone{{{1.webhookBody.phone}}}
firstName1.webhookBody.firstName{{{1.webhookBody.firstName}}}
campaignId1.webhookBody.campaignId{{{1.webhookBody.campaignId}}}
offerCode1.webhookBody.offerCode{{{1.webhookBody.offerCode}}}
Use these in Send Message nodes, AI prompts, HTTP tools, or any other node that accepts pipeline variables.

​
End-to-end example

Goal: When a user enters a win-back Journey in Iterable, trigger a Clerk Chat agent that sends a personalized SMS with their offer code.
  1. Clerk Chat: Create an agent with a Webhook trigger, an AI Text node, and a Send Message node. Reference {{{1.webhookBody.firstName}}} and {{{1.webhookBody.offerCode}}} in the AI prompt or message body. Connect the agent to an SMS inbox and deploy.
  2. Iterable: Create a Journey webhook pointing at your Agent Webhook URL with the apiKey header and a JSON body containing phone, firstName, and offerCode.
  3. Iterable: Add a Webhook tile to your win-back Journey using that webhook.
  4. Test: Enroll a test user in the Journey. When they reach the Webhook tile, Iterable POSTs to Clerk Chat and the agent sends the personalized message.

​
Troubleshooting

IssueSolution
401 Unauthorized from Clerk ChatVerify the apiKey custom header is set on the Iterable webhook
Agent doesn’t runConfirm the webhook URL matches the one on your agent’s trigger node, and the agent is deployed with an inbox connection
Wrong or missing contactEnsure the Iterable body includes phone with a valid E.164 number (e.g. +15551234567)
Agent runs but fields are emptyCheck Iterable merge parameters — field names must match what you reference in the agent (e.g. firstName vs first_name)
Iterable webhook failsConfirm the endpoint URL uses https:// and returns 202 from Clerk Chat

Agent Webhooks Overview

Learn how Agent Webhooks work and when to use them.

Trigger an Agent with a Webhook

Generic webhook setup, payload reference, and API details.