Copy page

Core Concepts

Webhook Events

Neuratel dispatches webhook events to your server when key actions occur — calls starting and ending, campaigns progressing, and DNC entries being added. Use webhooks to trigger downstream workflows, update CRM records, or build custom dashboards.

Available Events

The following event types are defined in the API and available for subscription. Events not yet dispatched in production are marked accordingly.

Event	When Fired	Status
call.started	A call begins	✅ Dispatched
call.ended	Call ends	✅ Dispatched
call.failed	Call fails (error, timeout, etc.)	✅ Dispatched
call.ringing	Outbound call is ringing	Reserved
call.answered	Call is answered	Reserved
call.transferred	Call transferred to another destination	Reserved
call.summary.ready	Post-call summary and analysis are available	Reserved
transcript.partial	Partial transcript available during call	Reserved
transcript.final	Final utterance transcribed	Reserved
transcript.ready	Full transcript available after call	Reserved
recording.ready	Recording upload is complete	Reserved
agent.turn.started	Agent begins generating a response	Reserved
agent.turn.ended	Agent finishes a response turn	Reserved
agent.tool.called	Agent invokes a tool/function	Reserved
campaign.started	Campaign begins dialing	✅ Dispatched
campaign.paused	Campaign is paused	✅ Dispatched
campaign.resumed	Campaign is resumed	✅ Dispatched
campaign.stopped	Campaign is manually stopped	✅ Dispatched
campaign.cancelled	Campaign is cancelled before completion	✅ Dispatched
campaign.completed	Campaign finishes all contacts	✅ Dispatched
campaign.retry_scheduled	A failed call is scheduled for retry	✅ Dispatched
dnc.added	A phone number is added to the DNC list	✅ Dispatched

"Reserved" events are defined in the API schema but not yet dispatched in production. They are available for subscription and will be activated in a future release.

Event Timing

• call.ended fires immediately when the call disconnects — use this for fast notifications.
• campaign.completed fires after all contacts in the campaign have been dialed.

Configuration

Per-Agent Webhooks

Configure webhooks in the agent's analytics.webhook section:

Code
{
  "config": {
    "analytics": {
      "webhook": {
        "url": "https://your-server.com/neuratel-webhook",
        "events": ["call.ended", "call.summary.ready"]
      }
    }
  }
}

Platform-Level Subscriptions

Subscribe to events from any call across your organization:

Code
curl -X POST https://api.neuratel.ai/v1/webhooks \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/neuratel-webhook",
    "events": ["call.ended", "call.summary.ready", "call.failed"],
    "description": "Production webhook for all call events"
  }'

Delivery

Signing

Every webhook request includes an HMAC-SHA256 signature in the X-Webhook-Signature header and a timestamp in X-Webhook-Timestamp. Verify the signature to ensure the request came from Neuratel and was not tampered with.

The signature is the raw lowercase hex digest of the HMAC — there is no sha256= prefix.

Retry Policy

Attempt	Delay
1st retry	5 seconds
2nd retry	30 seconds
3rd retry	2 minutes

After 10 consecutive failures, the webhook is automatically disabled. Re-enable it from the dashboard or API after fixing the issue.

Expected Response

Your endpoint must return a 2xx status code within the configured timeout (default 30 seconds, range 1–60). Any other response (or timeout) is treated as a failure and triggers a retry.

Signature Verification

Verify webhook signatures to ensure authenticity.

Python

Code
import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your webhook handler:
# signature = request.headers["X-Webhook-Signature"]
# timestamp = request.headers["X-Webhook-Timestamp"]
# payload = request.body  # raw bytes
# secret = "your_webhook_secret"
# if not verify_webhook(payload, signature, secret):
#     return 403

Node.js

Code
const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler:
// const signature = req.headers["x-webhook-signature"];
// const timestamp = req.headers["x-webhook-timestamp"];
// const payload = req.rawBody; // raw request body
// const secret = "your_webhook_secret";
// if (!verifyWebhook(payload, signature, secret)) {
//   return res.status(403).send("Invalid signature");
// }

Testing

Send a test event to your webhook endpoint:

Code
curl -X POST https://api.neuratel.ai/v1/webhooks/{webhook_id}/test \
  -H "Authorization: Bearer nk_live_your_api_key"

This sends a synthetic event to your configured URL so you can verify your handler works correctly.

Key Operations

Operation	Method	Endpoint
Create webhook	POST	/v1/webhooks
List webhooks	GET	/v1/webhooks
List available events	GET	/v1/webhooks/events
Get webhook	GET	/v1/webhooks/{id}
Update webhook	PATCH	/v1/webhooks/{id}
Delete webhook	DELETE	/v1/webhooks/{id}
Rotate secret	POST	/v1/webhooks/{id}/secret/rotate
Get delivery logs	GET	/v1/webhooks/{id}/logs
Test delivery	POST	/v1/webhooks/{id}/test