Webhooks

Webhooks deliver real-time event notifications to your server whenever something happens in your Zentrix Agent Studio account -- a call starts, a payment succeeds, or a subscription changes status. Instead of polling the API, you register a webhook URL and receive HTTP POST requests with event data as they occur.

Webhook Endpoints

Zentrix Agent Studio uses two webhook endpoints internally:

Call Events

These events fire during the lifecycle of a voice call (both phone and web widget):

Call Event Payload Example

{
  "event": "call.ended",
  "timestamp": "2026-03-05T14:30:00.000Z",
  "data": {
    "callId": "call_abc123",
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "instanceId": "660f9500-f30c-52e5-b827-557766551111",
    "platform": "phone",
    "callerNumber": "+919876543210",
    "duration": 245,
    "transcript": "Agent: Hello, how can I help you today? ...",
    "sentiment": "positive",
    "summary": "Customer inquired about product return policy. Provided return window details and initiated return process.",
    "disconnectionReason": "agent_ended"
  }
}

Payment Events

These events fire when subscription or payment status changes:

Signature Verification

All webhook requests include a signature header for security. Always verify the signature before processing events.

Call webhooks include x-webhook-signature:

import crypto from 'crypto';

function verifyCallWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Payment webhooks (Razorpay) include x-razorpay-signature:

function verifyPaymentWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return expected === signature;
}

Webhook Reliability

• Retry policy: If your endpoint returns a non-2xx status code, the webhook is retried up to 3 times with exponential backoff (1 min, 5 min, 30 min).
• Timeout: Your endpoint must respond within 10 seconds. Use a queue for heavy processing.
• Idempotency: Events may be delivered more than once. Use the callId or paymentId as an idempotency key to avoid duplicate processing.
• Ordering: Events are delivered in approximate chronological order, but network delays can cause out-of-order delivery. Check the timestamp field.

Best Practices

1. Respond with 200 immediately, then process the event asynchronously.
2. Log all incoming events for debugging and audit trails.
3. Verify signatures on every request to prevent spoofed events.
4. Handle unknown events gracefully -- return 200 for event types you don't recognize. New event types may be added in the future.

A Product by BRTNeura Technology LLP