Webhooks Overview

Send real-time event notifications to external systems when things happen in AlonChat

Webhooks Overview#

Webhooks allow your AI agent to notify external systems in real time when events occur — such as new leads, messages, conversations, or training updates. Use them to integrate with CRMs, analytics platforms, notification services, and custom applications.

How Webhooks Work#

1. You configure a webhook endpoint URL for your agent
2. You select which event types to subscribe to
3. When an event occurs, AlonChat sends an HTTP POST request to your endpoint
4. Your endpoint verifies the signature and processes the event
5. If delivery fails, AlonChat retries with exponential backoff

Creating a Webhook#

From the Dashboard#

1. Go to your agent dashboard
2. Click Settings > Webhooks
3. Click Add Webhook
4. Enter your endpoint URL (must be HTTPS)
5. Select the events you want to receive
6. Copy and securely store the signing secret
7. Save

Via the API#

Endpoint: POST /api/agents/{agentId}/webhooks

{
  "name": "My CRM Integration",
  "endpoint_url": "https://your-server.com/webhooks/alonchat",
  "events": ["leads.submit", "conversation.ended"],
  "description": "Sync leads to CRM",
  "custom_headers": {
    "X-Custom-Header": "value"
  }
}

Response:

{
  "id": "webhook-uuid",
  "secret_key": "whsec_xxxxxxxxxxxx"
}

Important: The secret_key is only returned once at creation time. Store it securely for signature verification. If lost, delete the webhook and create a new one.

Security#

AlonChat takes webhook security seriously with multiple layers of protection.

Signature Verification#

Every webhook request includes an HMAC-SHA256 signature so you can verify it came from AlonChat:

• Header: x-alonchat-signature
• Algorithm: HMAC-SHA256
• Format: sha256=<hex_digest>

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

See the Security guide for full verification examples in multiple languages.

Idempotency#

Each delivery includes an x-alonchat-delivery-id header. Use this to detect and deduplicate retried deliveries.

URL Validation#

• HTTPS required — all webhook endpoints must use HTTPS (except localhost during development)
• SSRF protection — AlonChat blocks delivery to private IP ranges and internal networks

Request Format#

All webhook requests are sent as HTTP POST with these headers:

Plus any custom headers you configured.

Payload Structure#

{
  "event": "leads.submit",
  "timestamp": "2026-03-15T12:00:00Z",
  "agent_id": "agent-uuid",
  "data": {
    "conversationId": "conv-uuid",
    "customerEmail": "john@example.com",
    "customerName": "John Doe"
  }
}

All timestamps are ISO 8601 format in UTC.

Available Events#

See Event Types for detailed payload examples.

Retry Policy#

Failed deliveries are retried automatically with exponential backoff:

A delivery is considered failed if your endpoint:

• Returns a non-2xx HTTP status code
• Does not respond within 10 seconds
• Is unreachable

After 5 failed attempts, the delivery is marked as failed and logged.

Circuit Breaker#

If a webhook endpoint fails consistently, AlonChat automatically pauses deliveries to that endpoint. This prevents unnecessary load on both systems. You can re-enable the webhook from the dashboard once the underlying issue is resolved.

Managing Webhooks#

List Webhooks#

GET /api/agents/{agentId}/webhooks

Returns all webhooks for the agent. Secret keys are masked.

{
  "webhooks": [
    {
      "id": "webhook-uuid",
      "name": "My CRM Integration",
      "endpoint_url": "https://your-server.com/webhooks/alonchat",
      "events": ["leads.submit"],
      "is_active": true,
      "secret_key_preview": "whsec_xxxx...xxxx",
      "created_at": "2026-01-15T00:00:00Z"
    }
  ]
}

Update Webhook#

PATCH /api/agents/{agentId}/webhooks/{webhookId}

Update the name, endpoint URL, events, or custom headers.

Delete Webhook#

DELETE /api/agents/{agentId}/webhooks/{webhookId}

Permanently removes the webhook. In-flight deliveries may still complete.

Test Webhook#

POST /api/agents/{agentId}/webhooks/{webhookId}/test

Sends a test event to your endpoint so you can verify it is working. Test events include a "test": true field in the payload.

Webhook Logs#

View delivery history and debug failures from the dashboard or API:

GET /api/agents/{agentId}/webhooks/{webhookId}/logs

Each log entry includes:

• Event type and timestamp
• HTTP status code returned by your endpoint
• Response time
• Whether the delivery succeeded or failed
• Number of retry attempts

Best Practices#

1. Respond quickly — return a 200 status as fast as possible, then process the event asynchronously.
2. Implement idempotency — use the x-alonchat-delivery-id header to handle duplicate deliveries.
3. Verify signatures — always validate the x-alonchat-signature header before processing.
4. Subscribe selectively — only subscribe to events you need. This reduces traffic and processing overhead.
5. Monitor your logs — check webhook delivery logs regularly to catch failures early.

Next Steps#

• Event Types — Detailed payload examples for every event
• Security — Signature verification in multiple languages
• Examples — Real-world integration recipes