Skip to content
  • api
  • webhooks

Webhooks

Webhooks let your application receive HTTP POST requests when events happen in ChatAgent — new conversations, messages, orders, and more.

Setting up webhooks

Section titled “Setting up webhooks”
  1. Go to Settings → API → Webhooks
  2. Click Add Webhook
  3. Enter your endpoint URL
  4. Select which events to subscribe to
  5. Save

Event types

Section titled “Event types”
Event Fires when Payload
conversation.created New conversation starts Contact info, platform, first message
message.received Message received Message content, contact, conversation ID
message.sent Message sent (AI or human) Message content, sender, conversation ID
conversation.resolved Conversation marked resolved Summary, duration, outcome
order.placed Order completed Order details, customer, products
contact.created New contact added Contact info
contact.updated Contact modified Changed fields
workflow.completed Workflow finished Workflow ID, steps completed

Payload format

Section titled “Payload format”

All webhooks send a JSON POST body:

{
  "event": "message.received",
  "timestamp": "2026-01-15T10:30:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "message": {
      "id": "msg_xyz789",
      "content": "Do you have this in blue?",
      "sender": "customer",
      "platform": "whatsapp"
    },
    "contact": {
      "id": "cnt_123",
      "name": "John Doe",
      "phone": "+1234567890"
    }
  }
}

Verifying webhooks

Section titled “Verifying webhooks”

Every webhook includes a signature header for verification:

X-ChatAgent-Signature: sha256=xxxxxxxxxxxx

Verify it:

const crypto = require("crypto");


function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

Retry policy

Section titled “Retry policy”

Failed deliveries (non-2xx response or timeout) are retried:

Attempt Delay
1 Immediate
2 1 minute
3 5 minutes
4 30 minutes
5 2 hours

After 5 failed attempts, the event is logged as failed and no more retries are attempted.

Monitoring

Section titled “Monitoring”

View webhook delivery status in Settings → API → Webhooks → Activity:

  • Delivered — successful delivery with response code
  • Failed — delivery failed after all retries
  • Pending — retry in progress

Tips

Section titled “Tips”
  • Respond quickly — return a 2xx status within 5 seconds
  • Process asynchronously — queue events for background processing
  • Handle duplicates — use the message.id to deduplicate
  • Monitor failures — set up alerts for repeated failures

Next steps

Section titled “Next steps”