Trigger an Agent with a Webhook

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.

This page covers inbound Agent Webhooks (external platform → Clerk Chat agent). For outbound event webhooks where Clerk Chat notifies your app, see Webhooks.

1. Add a Webhook trigger to your agent

Sign in at clerk.ai and open your agent in the Agents builder.
Click the Trigger node to open the trigger settings.
Under Trigger option, open Other and select Webhook.
Select an existing webhook from the dropdown, or click Add new to create one with a name.
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.

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.

Go to Settings → API.
Click Generate (or Generate New Key).
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

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:

{
  "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 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

Connect Iterable

Trigger agents from Iterable Journey or System webhooks.

Get Started

AI Agents

Integrations

Trigger an Agent with a Webhook

Overview

1. Add a Webhook trigger to your agent

2. Generate an API key

3. Send a webhook request

Headers

Request body

Example

Response

4. Use webhook data in your agent

Example payload → variable mapping

Rate limits

Troubleshooting

Platform-specific guides

Connect Iterable

​Overview

​1. Add a Webhook trigger to your agent

​2. Generate an API key

​3. Send a webhook request

​Headers

​Request body

​Example

​Response

​4. Use webhook data in your agent

​Example payload → variable mapping

​Rate limits

​Troubleshooting

​Platform-specific guides

Connect Iterable

Overview

1. Add a Webhook trigger to your agent

2. Generate an API key

3. Send a webhook request

Headers

Request body

Example

Response

4. Use webhook data in your agent

Example payload → variable mapping

Rate limits

Troubleshooting

Platform-specific guides