Copy page

Integrations

Webhooks

Webhooks deliver real-time event notifications to your server via HTTP POST. Instead of polling the API, your server receives events the moment they occur — call ended, recording ready, analysis complete.

How Webhooks Work

1. An event occurs in Neuratel (e.g., a call ends)
2. Neuratel sends an HTTP POST to your configured URL
3. Your server verifies the signature and returns HTTP 200
4. If delivery fails, Neuratel retries with exponential backoff

Event Types

Event	When It Fires
call.started	When a call begins
call.ended	Immediately when a call ends
call.ringing	Outbound call is ringing
call.answered	Call is answered
call.failed	When an error occurs during a call
call.transferred	Call transferred to another destination
call.summary.ready	When post-call analysis (summary, transcript, evaluation) is complete. Includes recording_url if recording is enabled.
recording.ready	Coming soon — defined in the API but not yet emitted. Recording URLs are surfaced on call.summary.ready and on the voice session record.

Quick Start

1. Create a Webhook Endpoint

Your endpoint receives POST requests and must return 200.

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

app = FastAPI()
WEBHOOK_SECRET = "whsec_your_signing_secret"

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

    if not signature or not verify_signature(body, signature, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()
    event_type = payload["meta"]["event_type"]

    match event_type:
        case "call.summary.ready":
            # Includes recording_url if recording was enabled on the agent.
            await handle_call_summary(payload["data"])
        case "call.ended":
            await handle_call_ended(payload["data"])

    return {"status": "ok"}

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

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

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

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

    const expected = crypto
      .createHmac("sha256", WEBHOOK_SECRET)
      .update(body)
      .digest("hex");

    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).send("Invalid signature");
    }

    const { meta, data } = JSON.parse(body);

    switch (meta.event_type) {
      case "call.summary.ready":
        handleCallSummary(data);
        break;
      case "call.ended":
        handleCallEnded(data);
        break;
    }

    res.json({ status: "ok" });
  }
);

2. Register the 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 '{
    "name": "Production Events",
    "url": "https://your-server.com/webhooks/neuratel",
    "events": ["call.ended", "call.summary.ready", "call.failed"],
    "timeout_seconds": 30
  }'

Response:

Code
{
  "id": "wh_abc123",
  "name": "Production Events",
  "url": "https://your-server.com/webhooks/neuratel",
  "events": ["call.ended", "call.summary.ready", "call.failed"],
  "is_active": true,
  "secret": "whsec_your_signing_secret",
  "created_at": "2025-04-07T10:00:00Z"
}

Store secret immediately — it is shown only once.

3. Test the Webhook

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

Check delivery logs:

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

Event Payloads

All events share a common envelope:

Code
{
  "meta": {
    "event_id": "evt_abc123",
    "event_type": "call.summary.ready",
    "timestamp": "2025-04-07T10:35:45Z",
    "webhook_id": "wh_abc123",
    "organization_id": "org_xyz789",
    "is_test": false
  },
  "data": { ... }
}

call.summary.ready

The most comprehensive event. Fires after a call ends and all processing is complete.

Code
{
  "meta": {
    "event_id": "evt_abc123",
    "event_type": "call.summary.ready",
    "timestamp": "2025-04-07T10:35:45Z"
  },
  "data": {
    "call_id": "call_def456",
    "agent_id": "agent_xyz789",
    "agent_name": "Support Agent",
    "call_type": "inbound",
    "phone_number": "+14155550101",
    "caller_number": "+12125550182",
    "started_at": "2025-04-07T10:30:00Z",
    "ended_at": "2025-04-07T10:35:45Z",
    "duration_seconds": 345,
    "outcome": "completed",
    "end_reason": "caller_hangup",
    "recording_url": "https://storage.googleapis.com/neuratel-recordings/call_def456.ogg",
    "transcript": [
      {
        "role": "agent",
        "text": "Thank you for calling. How can I help you today?",
        "timestamp": "2025-04-07T10:30:01Z"
      },
      {
        "role": "user",
        "text": "I need to check on my order.",
        "timestamp": "2025-04-07T10:30:05Z"
      }
    ],
    "analysis": {
      "sentiment": "positive",
      "summary": "Caller inquired about order status. Agent confirmed order shipped.",
      "success": true,
      "rubric_scores": [
        { "name": "verified_identity", "passed": true, "score": 1.0 },
        { "name": "resolved_issue", "passed": true, "score": 1.0 }
      ]
    }
  }
}

call.ended

Lightweight event fired immediately when a call ends, before transcript and analysis are ready.

Code
{
  "meta": {
    "event_id": "evt_ghi789",
    "event_type": "call.ended",
    "timestamp": "2025-04-07T10:35:45Z"
  },
  "data": {
    "call_id": "call_def456",
    "agent_id": "agent_xyz789",
    "duration_seconds": 345,
    "outcome": "completed",
    "end_reason": "caller_hangup"
  }
}

recording.ready (coming soon — not yet emitted in production)

This event is defined in the API enum but not yet emitted by the platform. Subscribing to it has no effect today. For now, retrieve the recording URL from the call.summary.ready event payload, or fetch it on demand via GET /v1/voice-sessions/{id} (the response includes recording.recording_url when recording was enabled).

Preview of the payload shape (subject to change before launch):

Code
{
  "meta": {
    "event_id": "evt_jkl012",
    "event_type": "recording.ready",
    "timestamp": "2025-04-07T10:36:00Z"
  },
  "data": {
    "call_id": "call_def456",
    "recording_url": "https://storage.googleapis.com/neuratel-recordings/call_def456.ogg",
    "duration_seconds": 345,
    "file_size_bytes": 2867200
  }
}

call.failed

Code
{
  "meta": {
    "event_id": "evt_pqr678",
    "event_type": "call.failed",
    "timestamp": "2025-04-07T10:30:05Z"
  },
  "data": {
    "call_id": "call_stu901",
    "error_code": "EXTERNAL_6001",
    "error_message": "Provider unavailable",
    "occurred_at": "2025-04-07T10:30:05Z"
  }
}

Retry Policy

If your endpoint does not return a 2xx status within the timeout window, Neuratel retries:

Attempt	Delay
1	5 seconds
2	30 seconds
3	2 minutes

After 3 failed attempts, the delivery is marked failed. Webhooks are automatically disabled after 10 consecutive delivery failures — re-enable via the dashboard or PATCH /v1/webhooks/{id} with is_active: true.

Managing Webhooks

Update Webhook

Code
curl -X PATCH https://api.neuratel.ai/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"events": ["call.summary.ready", "call.failed"]}'

Rotate Signing Secret

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

The old secret is invalidated immediately. Update your handler before rotating.

Disable / Enable

Code
curl -X PATCH https://api.neuratel.ai/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Delete Webhook

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

Local Development

Use ngrok or Cloudflare Tunnel to expose your local server:

Code
# ngrok
ngrok http 8000

# Your tunnel URL: https://abc123.ngrok.io
# Register: POST /v1/webhooks with url: "https://abc123.ngrok.io/webhooks/neuratel"

Best Practices

Return 200 Immediately, Process Asynchronously

Do not perform heavy processing in the request handler. Return 200 right away and offload work to a background task or queue.

Code
from fastapi import BackgroundTasks

@app.post("/webhooks/neuratel")
async def receive_webhook(request: Request, background_tasks: BackgroundTasks):
    payload = await request.json()
    background_tasks.add_task(process_event, payload)
    return {"status": "ok"}

Implement Idempotency

Neuratel guarantees at-least-once delivery. The same event may arrive more than once. Use meta.event_id to deduplicate:

Code
processed_ids: set[str] = set()  # use a persistent store in production

async def process_event(payload: dict):
    event_id = payload["meta"]["event_id"]
    if event_id in processed_ids:
        return
    processed_ids.add(event_id)
    # process...

Verify Every Request

Always verify the X-Webhook-Signature header before processing any payload. Do not trust requests without a valid signature.

API Reference

Endpoint	Method	Description
/v1/webhooks	GET	List webhooks
/v1/webhooks	POST	Create webhook
/v1/webhooks/{id}	GET	Get webhook details
/v1/webhooks/{id}	PATCH	Update webhook
/v1/webhooks/{id}	DELETE	Delete webhook
/v1/webhooks/{id}/test	POST	Send test event
/v1/webhooks/{id}/logs	GET	View delivery logs
/v1/webhooks/{id}/secret/rotate	POST	Rotate signing secret

Next Steps

• Security — detailed webhook signature verification
• MCP Tools — connect external tools to your agents
• Error Codes — handle delivery errors