> ## 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.

# Trigger an Agent with a Webhook

> Configure an Agent Webhook trigger and invoke it from any external system

## Overview

Agent Webhooks are inbound HTTP endpoints that trigger a specific AI Agent when called. This guide walks through setting up a webhook trigger in the agent builder, authenticating requests, sending payloads, and using webhook data inside your agent.

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

## 1. Add a Webhook trigger to your agent

1. Sign in at [clerk.ai](https://clerk.ai) and open your agent in the [Agents](https://clerk.ai/agents) builder.
2. Click the **Trigger** node to open the trigger settings.
3. Under **Trigger option**, open **Other** and select **Webhook**.
4. Select an existing webhook from the dropdown, or click **Add new** to create one with a name.
5. Copy the auto-generated URL shown below the dropdown.

The URL follows this pattern:

```
https://web-api.clerk.chat/public/pipelines/webhook/{webhookId}
```

Each webhook has a stable UUID (`webhookId`). The same webhook can be reused across agents, but each agent must have its trigger node configured to use that webhook.

6. Save and deploy your agent. Make sure the agent is connected to an inbox so it can send messages.

## 2. Generate an API key

Every request to an Agent Webhook must include your team's API key.

1. Go to **Settings → API**.
2. Click **Generate** (or **Generate New Key**).
3. Copy the key immediately — it is only shown once.

Send the key on every request using the `apiKey` HTTP header.

## 3. Send a webhook request

Make a `POST` request to your webhook URL with `Content-Type: application/json`.

### Headers

| Header         | Required | Description                               |
| -------------- | -------- | ----------------------------------------- |
| `apiKey`       | Yes      | Your team API key from **Settings → API** |
| `Content-Type` | Yes      | Must be `application/json`                |

### Request body

| Field               | Type   | Required | Description                                                                                                                                            |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `phone`             | string | No       | Contact phone number (normalized to E.164). When provided, Clerk Chat finds or creates a contact and routes the conversation to the appropriate inbox. |
| *(any other field)* | any    | No       | Additional top-level fields are passed through to the agent as part of `webhookBody`.                                                                  |

### Example

```bash theme={null}
curl -X POST "https://web-api.clerk.chat/public/pipelines/webhook/YOUR_WEBHOOK_ID" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15551234567",
    "campaignId": "winback-2026",
    "offerCode": "SAVE20"
  }'
```

### Response

A successful request returns **`202 Accepted`** with an empty body. Processing is asynchronous — the agent runs after the response is sent.

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `202`  | Request accepted; agent will run           |
| `400`  | Invalid request body                       |
| `401`  | Missing or invalid API key                 |
| `404`  | Webhook not found (wrong ID or wrong team) |
| `429`  | Rate limit exceeded                        |

## 4. Use webhook data in your agent

The full JSON body of the request is exposed on the trigger node as **`webhookBody`**. Reference fields in downstream nodes using the trigger node's static ID:

```
{triggerStaticId}.webhookBody.{fieldName}
```

For example, if your trigger node has static ID `1` and you sent `offerCode` in the payload:

```
1.webhookBody.offerCode
```

In template syntax (e.g. Send Message nodes):

```
{{{1.webhookBody.offerCode}}}
```

For AI text agents, the webhook payload is also included as a system message so the model can reason about the external event.

### Example payload → variable mapping

Request body:

```json theme={null}
{
  "phone": "+15551234567",
  "ticketId": "TKT-48291",
  "priority": "high"
}
```

Agent variable paths (assuming trigger static ID `1`):

| Payload field | Variable path            |
| ------------- | ------------------------ |
| `phone`       | `1.webhookBody.phone`    |
| `ticketId`    | `1.webhookBody.ticketId` |
| `priority`    | `1.webhookBody.priority` |

See [Referencing Variables](/referencing-variables) for more on variable syntax.

## Rate limits

Agent Webhook endpoints are rate-limited to **1,000 requests per 60 seconds** per team. If you exceed this limit, requests return `429 Too Many Requests`.

## Troubleshooting

| Issue                          | Solution                                                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`             | Verify the `apiKey` header is set and the key is active in **Settings → API**                                                              |
| `404 Webhook not found`        | Confirm the webhook ID in the URL matches the webhook selected on your agent's trigger node, and that the API key belongs to the same team |
| Agent doesn't run              | Ensure the agent is saved, deployed, and connected to an inbox                                                                             |
| Agent runs but no message sent | Check that downstream nodes (e.g. Send Message) are configured and the agent has a valid inbox connection                                  |
| Contact not associated         | Include a `phone` field in the request body so Clerk Chat can find or create the contact                                                   |

## Platform-specific guides

<Card title="Connect Iterable" icon="link" href="/integrations/agent-webhooks/iterable">
  Trigger agents from Iterable Journey or System webhooks.
</Card>