Webhooks

Overview

Webhooks allow you to receive real-time notifications when events happen in your Custom Agents account. Configure a URL endpoint and select the events you want to receive.

Events

Event	Description
`message.received`	A new message was received by an agent
`message.sent`	An agent sent a message
`message.drafted`	An agent drafted a message for review
`contact.created`	A new contact was added to the CRM
`contact.updated`	A contact's information was updated
`escalation.triggered`	An escalation rule was triggered
`agent.updated`	An agent's configuration was changed

Payload format

{
  "event": "message.received",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_xyz789",
    "agentId": "agent_abc123",
    "from": "customer@example.com",
    "subject": "Question about my order",
    "body": "Hi, I was wondering about the status of...",
    "threadId": "thread_def456"
  }
}

Setup

Via API

POST /v1/webhooks

{
  "url": "https://yourapp.com/webhook",
  "events": ["message.received", "message.sent", "escalation.triggered"],
  "secret": "your-webhook-secret"
}

Verification

All webhook payloads include an X-CustomAgents-Signature header. Verify the signature using your webhook secret to ensure the request came from Custom Agents.

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Connect your systems

Receive real-time events from your AI agents via webhooks.

Get API Key