Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Tellexa.

1. You register a webhook URL
2. Tellexa sends an HTTP POST request when events occur
3. Your server processes the event and responds with 200 OK

POST https://api.tellexa.ai/v1/webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "url": "https://yourapp.com/webhooks/tellexa",
  "events": ["message.created", "task.completed"],
  "secret": "your_webhook_secret"
}

{
  "id": "wh_abc123",
  "url": "https://yourapp.com/webhooks/tellexa",
  "events": ["message.created", "task.completed"],
  "active": true,
  "created_at": "2026-02-06T10:00:00Z"
}

Example payload for message.created:

{
  "id": "evt_xyz789",
  "type": "message.created",
  "created_at": "2026-02-06T10:30:00Z",
  "data": {
    "message_id": "msg_abc123",
    "assistant_id": "ast_def456",
    "content": "Your meeting with John has been scheduled for 3pm tomorrow.",
    "direction": "outbound"
  }
}

All webhooks are signed using your webhook secret. Verify the signature to ensure the request came from Tellexa.

X-Tellexa-Signature: sha256=...

const crypto = require('crypto');

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

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

If your endpoint fails, Tellexa will retry:

After 5 failed attempts, the webhook is marked as failing and you’ll receive an email notification.

• ✅ Respond with 200 OK quickly (within 5 seconds)
• ✅ Process events asynchronously
• ✅ Handle duplicate events (use id for deduplication)
• ✅ Log all received webhooks

• ✅ Always verify signatures
• ✅ Use HTTPS endpoints only
• ✅ Restrict inbound IPs if possible
• ✅ Rotate webhook secrets periodically

Questions? Contact API support →