Copy page

Guides

Events and Webhooks

Webhooks deliver real-time event notifications to your server via HTTP POST requests. Use them to sync call data with your CRM, trigger follow-up workflows, log activity, or alert your team.

Prerequisites: Neuratel account, a publicly accessible HTTPS endpoint

---

How webhooks work

1. You register a webhook URL and select which event types to receive.
2. When an event occurs, Neuratel sends an HTTP POST request to your URL.
3. Your server verifies the HMAC signature, processes the event, and returns 200 OK.
4. Failed deliveries are retried up to 3 times (5s, 30s, 2min delays).

---

Event types

Event	When it fires
call.started	A call has begun
call.ended	A call has ended (fires immediately, before analysis)
call.ringing	Outbound call is ringing
call.answered	Call has been answered
call.failed	An error occurred during a call
call.transferred	Call transferred to another destination
recording.ready	Coming soon — defined but not yet emitted. The recording URL is currently surfaced on call.summary.ready and on the voice session record.
call.summary.ready	Post-call analysis (summary, transcript, evaluation) is complete

---

Create a webhook

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/webhooks/neuratel",
    "events": ["call.ended", "call.summary.ready", "call.failed"],
    "headers": {
      "X-Custom-Auth": "your-internal-token"
    }
  }'

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_your_api_key"},
)

webhook = client.post("/v1/webhooks", json={
    "url": "https://your-server.com/webhooks/neuratel",
    "events": ["call.ended", "call.summary.ready", "call.failed"],
    "headers": {
        "X-Custom-Auth": "your-internal-token",
    },
}).json()

print(webhook["id"])      # wh_abc123
print(webhook["secret"])  # whsec_xxxx — save this, shown only once

Code
const webhook = await fetch("https://api.neuratel.ai/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nk_live_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/webhooks/neuratel",
    events: ["call.ended", "call.summary.ready", "call.failed"],
    headers: {
      "X-Custom-Auth": "your-internal-token",
    },
  }),
}).then((r) => r.json());

console.log(webhook.id);     // wh_abc123
console.log(webhook.secret); // whsec_xxxx — save this, shown only once

Response:

Code
{
  "id": "wh_abc123",
  "url": "https://your-server.com/webhooks/neuratel",
  "events": ["call.ended", "call.summary.ready", "call.failed"],
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
  "status": "active",
  "created_at": "2026-04-07T09:00:00Z"
}

The secret is returned only once at creation time. Store it securely — you will need it to verify signatures.

---

Verify webhook signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret.

Always verify signatures before processing events to ensure requests are authentic.

Code
import hmac
import hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "whsec_a1b2c3d4e5f6g7h8i9j0"

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

@app.post("/webhooks/neuratel")
async def handle_webhook(request: Request):
    signature = request.headers.get("X-Webhook-Signature", "")
    payload = await request.body()

    if not verify_webhook(payload, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    event_type = event["type"]
    data = event["data"]

    if event_type == "call.summary.ready":
        # Process completed call with full analysis
        print(f"Call {data['call_id']} completed — {data['duration_seconds']}s")
    elif event_type == "call.failed":
        # Alert your team
        print(f"Error on call {data['call_id']}: {data['error_message']}")

    return {"status": "ok"}

Code
const crypto = require("crypto");
const express = require("express");

const app = express();
const WEBHOOK_SECRET = "whsec_a1b2c3d4e5f6g7h8i9j0";

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

app.post("/webhooks/neuratel", express.raw({ type: "application/json" }), (req, res) => {
  const signature = req.headers["x-webhook-signature"];

  if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case "call.summary.ready":
      console.log(`Call ${event.data.call_id} completed`);
      break;
    case "call.failed":
      console.log(`Error: ${event.data.error_message}`);
      break;
  }

  res.status(200).send("OK");
});

---

Event payload structures

call.summary.ready

Fires when a call ends and the full transcript and analysis are available.

Code
{
  "id": "evt_001",
  "type": "call.summary.ready",
  "created_at": "2026-04-07T10:15:00Z",
  "data": {
    "call_id": "call_xyz789",
    "agent_id": "agent_abc123",
    "direction": "inbound",
    "from": "+14155550100",
    "to": "+14155550199",
    "duration_seconds": 94,
    "status": "completed",
    "transcript": [
      { "role": "assistant", "text": "Thanks for calling Acme Corp." },
      { "role": "user", "text": "I need to check my order status." }
    ],
    "summary": "Customer called to check order status. Agent confirmed order shipped.",
    "success": true
  }
}

call.ended

Fires immediately when a call disconnects, before analysis runs.

Code
{
  "id": "evt_002",
  "type": "call.ended",
  "created_at": "2026-04-07T10:15:00Z",
  "data": {
    "call_id": "call_xyz789",
    "agent_id": "agent_abc123",
    "duration_seconds": 94,
    "status": "completed",
    "end_reason": "caller_hangup"
  }
}

recording.ready

Fires when the call recording has been processed.

Code
{
  "id": "evt_003",
  "type": "recording.ready",
  "created_at": "2026-04-07T10:16:00Z",
  "data": {
    "call_id": "call_xyz789",
    "recording_url": "https://recordings.neuratel.ai/call_xyz789.mp3",
    "duration_seconds": 94
  }
}

call.failed

Fires when an error occurs during a call.

Code
{
  "id": "evt_005",
  "type": "call.failed",
  "created_at": "2026-04-07T10:15:30Z",
  "data": {
    "call_id": "call_xyz789",
    "agent_id": "agent_abc123",
    "error_code": "tool_timeout",
    "error_message": "Tool 'check_order_status' timed out after 10 seconds"
  }
}

---

Test a webhook

Send a test event to verify your endpoint is reachable and processes events correctly.

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

This sends a synthetic call.summary.ready event to your registered URL.

---

View delivery logs

Check the delivery history for a webhook to debug failures.

Code
curl "https://api.neuratel.ai/v1/webhooks/wh_abc123/logs" \
  -H "Authorization: Bearer nk_live_your_api_key"

Response:

Code
{
  "items": [
    {
      "event_id": "evt_001",
      "event_type": "call.summary.ready",
      "status": "delivered",
      "response_code": 200,
      "latency_ms": 142,
      "delivered_at": "2026-04-07T10:15:01Z"
    },
    {
      "event_id": "evt_002",
      "event_type": "call.ended",
      "status": "failed",
      "response_code": 500,
      "attempt": 3,
      "next_retry_at": "2026-04-07T10:45:00Z"
    }
  ]
}

---

Rotate webhook secret

If your secret is compromised, rotate it immediately. The old secret becomes invalid as soon as the new one is generated.

Code
curl -X POST https://api.neuratel.ai/v1/webhooks/wh_abc123/secret/rotate \
  -H "Authorization: Bearer nk_live_your_api_key"

Response:

Code
{
  "secret": "whsec_new_secret_value"
}

Update your server with the new secret before the next event delivery.

---

Retry policy

Attempt	Delay
1	5 seconds
2	30 seconds
3	2 minutes

After 3 failed attempts the delivery is marked as failed. Webhooks are automatically disabled after 10 consecutive delivery failures — re-enable via the dashboard or PATCH /v1/webhooks/{id} with is_active: true. Your server must return a 2xx status code within 5 seconds for the delivery to count as successful.

---

Best practices

Practice	Reason
Return 200 immediately, process async	Webhook timeout is 5 seconds — queue the event and process in the background
Always verify signatures	Prevents spoofed requests from reaching your business logic
Handle events idempotently	The same event may be delivered more than once during retries
Log raw payloads	Makes debugging delivery issues easier
Rotate secrets periodically	Limits exposure if credentials leak

---

Related

• Building Your First Agent
• Agent Lifecycle
• Workflow Builder