Webhooks

Webhooks let your systems receive real-time events from the platform — call started, ended, transferred, transcript ready, and campaign state changes.

List webhooks

GET /v1/webhooks
Scope: voice:webhooks:read

{
  "webhooks": [
    {
      "uuid": "wbh_w1x2y3",
      "name": "CRM Sync",
      "url": "https://workflow.example.com/nn-events",
      "events": ["call.ended", "call.started"],
      "is_active": true,
      "last_triggered_at": "2026-05-12T14:34:00Z"
    }
  ]
}

---

Register webhook

POST /v1/webhooks — Rate limit: 20/minute
Scope: voice:webhooks:write

{
  "name": "CRM Sync",
  "url": "https://workflow.example.com/nn-events",
  "events": ["call.ended", "call.started", "call.transferred"],
  "headers": {
    "X-Workflow-Secret": "your-shared-secret"
  }
}

Field	Type	Required	Notes
name	string	✓
url	string	✓	HTTPS endpoint receiving POST requests
events	string[]	✓	One or more event types (see table below)
headers	object	—	Custom headers sent with every delivery

---

Delete webhook

DELETE /v1/webhooks/{webhook_id}
Scope: voice:webhooks:write

---

Delivery logs

GET /v1/webhooks/{webhook_id}/logs
Scope: voice:webhooks:read

Query parameters: limit (default 50, max 100), offset

{
  "logs": [
    {
      "uuid": "wbl_l1m2n3",
      "event_type": "call.ended",
      "response_status": 200,
      "success": true,
      "triggered_at": "2026-05-12T14:34:05Z"
    }
  ]
}

---

Event types

Event	Fired when
call.started	A call connects (human voice detected)
call.ended	A call terminates — includes full transcript and outcome
call.transferred	AI initiates a warm transfer to a human agent
call.no_answer	Call goes unanswered after ring timeout
call.voicemail	Voicemail detected — auto-disconnected
campaign.launched	Outbound campaign starts
campaign.stopped	Outbound campaign stops
campaign.completed	All contacts in the campaign have been dialled

---

Event payload envelope

Every delivery is a POST to your URL with this structure:

{
  "event": "call.ended",
  "fired_at": "2026-05-12T14:34:05Z",
  "organisation_uuid": "org_o1p2q3",
  "data": {
    "call_uuid": "cal_c1d2e3f4",
    "call_type": "outbound",
    "campaign_uuid": "flw_f1g2h3",
    "contact_uuid": "cst_c1d2e3",
    "contact_phone": "+14155550192",
    "contact_metadata": {
      "lead_id": "LH-CA-2026050512-78231",
      "cart_value": 850
    },
    "outcome": "connected",
    "sentiment": "positive",
    "duration_seconds": 113,
    "language_detected": "en",
    "transcript": [
      { "speaker": "agent",    "text": "Hi, good morning!", "timestamp": 0.0 },
      { "speaker": "customer", "text": "Yes I was looking at that desk.", "timestamp": 6.2 }
    ],
    "recording_url": "https://api.nextneural.ai/api/voice/calls/cal_c1d2e3f4/recording",
    "started_at": "2026-05-12T14:32:01Z",
    "ended_at": "2026-05-12T14:34:00Z"
  }
}

Delivery behaviour

• Retries: Up to 3 attempts with exponential backoff on non-2xx responses
• Timeout: Respond within 10 seconds or the delivery is marked failed and retried
• Signature: Verify deliveries using the X-NN-Signature header — HMAC-SHA256 of the raw body signed with your webhook secret