Skip to main content

​
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

  1. Sign in at clerk.ai and open your agent in the 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.
  1. 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

HeaderRequiredDescription
apiKeyYesYour team API key from Settings → API
Content-TypeYesMust be application/json

​
Request body

FieldTypeRequiredDescription
phonestringNoContact 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)anyNoAdditional 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.
StatusMeaning
202Request accepted; agent will run
400Invalid request body
401Missing or invalid API key
404Webhook not found (wrong ID or wrong team)
429Rate 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 fieldVariable path
phone1.webhookBody.phone
ticketId1.webhookBody.ticketId
priority1.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

IssueSolution
401 UnauthorizedVerify the apiKey header is set and the key is active in Settings → API
404 Webhook not foundConfirm 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 runEnsure the agent is saved, deployed, and connected to an inbox
Agent runs but no message sentCheck that downstream nodes (e.g. Send Message) are configured and the agent has a valid inbox connection
Contact not associatedInclude 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.