> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clerk.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Iterable

> Trigger Clerk Chat AI Agents from Iterable Journey and System webhooks

## Overview

Iterable can trigger Clerk Chat AI Agents by sending HTTP requests to an [Agent Webhook](/integrations/agent-webhooks/overview). 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.

<Note>
  This page covers **inbound** Agent Webhooks (Iterable → Clerk Chat agent). For **outbound** event webhooks where Clerk Chat notifies your app, see [Webhooks](/integrations/webhooks).
</Note>

## 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](/integrations/agent-webhooks/webhook-trigger).
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

## Recommended approach: Journey webhooks

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:

| Setting            | Value                                                    |
| ------------------ | -------------------------------------------------------- |
| **Name**           | A descriptive label (e.g. `Clerk Chat Agent Trigger`)    |
| **HTTP method**    | `POST`                                                   |
| **Endpoint**       | Your Agent Webhook URL from the Clerk Chat agent builder |
| **Authentication** | Custom HTTP headers                                      |

4. Under **Custom HTTP headers**, add:

| Header name | Header value            |
| ----------- | ----------------------- |
| `apiKey`    | Your Clerk Chat API key |

5. Set the **request body** to JSON. Include `phone` plus any fields you want the agent to use:

```json theme={null}
{
  "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.

<Warning>
  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.
</Warning>

6. 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:

| Setting                 | Value                                            |
| ----------------------- | ------------------------------------------------ |
| **Endpoint URL**        | Your Agent Webhook URL                           |
| **Status**              | Enabled                                          |
| **Authentication**      | None (use custom headers instead)                |
| **Custom HTTP headers** | `apiKey: YOUR_CLERK_CHAT_API_KEY`                |
| **Triggering events**   | Select the events that should trigger your agent |

<Note>
  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.
</Note>

4. 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:

```json theme={null}
{
  "phone": "+15551234567",
  "firstName": "Jane",
  "campaignId": "winback-q2",
  "offerCode": "SAVE20"
}
```

And your trigger node has static ID `1`, reference fields like this:

| Iterable field | Agent variable path        | Template example                 |
| -------------- | -------------------------- | -------------------------------- |
| `phone`        | `1.webhookBody.phone`      | `{{{1.webhookBody.phone}}}`      |
| `firstName`    | `1.webhookBody.firstName`  | `{{{1.webhookBody.firstName}}}`  |
| `campaignId`   | `1.webhookBody.campaignId` | `{{{1.webhookBody.campaignId}}}` |
| `offerCode`    | `1.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

| Issue                              | Solution                                                                                                                    |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` from Clerk Chat | Verify the `apiKey` custom header is set on the Iterable webhook                                                            |
| Agent doesn't run                  | Confirm the webhook URL matches the one on your agent's trigger node, and the agent is deployed with an inbox connection    |
| Wrong or missing contact           | Ensure the Iterable body includes `phone` with a valid E.164 number (e.g. `+15551234567`)                                   |
| Agent runs but fields are empty    | Check Iterable merge parameters — field names must match what you reference in the agent (e.g. `firstName` vs `first_name`) |
| Iterable webhook fails             | Confirm the endpoint URL uses `https://` and returns `202` from Clerk Chat                                                  |

## Related

<CardGroup cols={2}>
  <Card title="Agent Webhooks Overview" icon="book" href="/integrations/agent-webhooks/overview">
    Learn how Agent Webhooks work and when to use them.
  </Card>

  <Card title="Trigger an Agent with a Webhook" icon="bolt" href="/integrations/agent-webhooks/webhook-trigger">
    Generic webhook setup, payload reference, and API details.
  </Card>
</CardGroup>