API Integrations

Webhooks

Receive real-time notifications when events occur in your AI agents. Webhooks allow you to build event-driven integrations and keep external systems synchronized with agent activities.

Features

  • Real-time event delivery
  • Signature verification (HMAC SHA-256)
  • Automatic retries on failure
  • Event filtering
  • Idempotency keys
  • Delivery status tracking
  • Webhook logs

Requirements

  • HTTPS webhook URL
  • Webhook secret for verification
  • Publicly accessible endpoint

Setup

  1. 1Connect "Webhooks" integration
  2. 2Select your agent
  3. 3Configure your webhook URL (must be HTTPS)
  4. 4Select events to subscribe to
  5. 5Copy webhook secret for signature verification
  6. 6Implement webhook endpoint in your application
  7. 7Verify webhook signatures for security
  8. 8Test webhook delivery

API Reference

Endpoint:POST /api/integrations/webhook

Authentication

HMAC SHA-256 signature verification

Webhook Events

  • message.createdNew message received
  • session.startedNew conversation session
  • session.endedConversation session closed
  • error.occurredError in processing
  • agent.updatedAgent configuration changed

Code Examples

JavaScript

// Express.js webhook handler
const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-centralai-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  console.log('Received event:', event.event, event.data);
  
  res.status(200).send('OK');
});

Python

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-CentralAI-Signature')
    secret = os.environ.get('WEBHOOK_SECRET')
    
    expected_signature = hmac.new(
        secret.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()
    
    if signature != expected_signature:
        return 'Invalid signature', 401
    
    event = request.json
    print(f"Event: {event['event']}")
    print(f"Data: {event['data']}")
    
    return 'OK', 200

Troubleshooting

Issue: Webhook not receiving events

Solution: Verify URL is HTTPS and publicly accessible, check firewall rules, verify webhook is active in dashboard

Issue: Invalid signature error

Solution: Ensure you're using the correct webhook secret and computing HMAC SHA-256 correctly

← Back to Integrations