Webhooks Overview

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

Webhooks Overview#

Webhooks allow your AI agent to notify external systems when events occur. This enables integration with CRMs, email systems, analytics platforms, and custom applications.

How Webhooks Work#

  1. You configure a webhook endpoint URL for your agent
  2. Select which event types to subscribe to
  3. AlonChat sends HTTP POST requests to your endpoint when events occur
  4. Your endpoint validates the signature and processes the event

Creating a Webhook#

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

Request Body#

json
{
  "name": "My Webhook",
  "endpoint_url": "https://your-server.com/webhook",
  "events": ["message.created", "lead.captured"],
  "description": "Optional description",
  "custom_headers": {
    "X-Custom-Header": "value"
  }
}

Response#

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

Important: The secret_key is only returned once on creation. Store it securely for signature verification.

Security Features#

URL Validation#

  • HTTPS required (except localhost in development)
  • SSRF protection blocks private IP ranges

Signature Verification#

Every webhook request includes a signature header for verification:

Code
X-Webhook-Signature: sha1=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The signature is generated using HMAC SHA-1:

javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha1', secret);
  hmac.update(JSON.stringify(payload));
  const expected = 'sha1=' + hmac.digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Listing Webhooks#

API Endpoint: GET /api/agents/{agentId}/webhooks

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

json
{
  "webhooks": [
    {
      "id": "webhook-uuid",
      "name": "My Webhook",
      "endpoint_url": "https://your-server.com/webhook",
      "events": ["message.created"],
      "is_active": true,
      "secret_key_preview": "whsec_xxxx...xxxx",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Managing Webhooks#

Update Webhook#

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

Delete Webhook#

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

Test Webhook#

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

Sends a test event to verify your endpoint is working.

Request Format#

All webhook requests are sent as HTTP POST with:

  • Content-Type: application/json
  • X-Webhook-Signature: sha1=...
  • Custom headers you configured

Payload Structure#

json
{
  "event": "message.created",
  "timestamp": "2024-01-01T12:00:00Z",
  "agent_id": "agent-uuid",
  "data": {
    // Event-specific data
  }
}

Retry Logic#

Failed webhook deliveries are retried with exponential backoff:

  • Attempt 1: Immediate
  • Attempt 2: 1 minute
  • Attempt 3: 5 minutes
  • Attempt 4: 30 minutes
  • Attempt 5: 2 hours

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

Webhook Logs#

View delivery history and debug failures: GET /api/agents/{agentId}/webhooks/{webhookId}/logs

Next Steps#

Webhooks Overview | AlonChat Docs