Webhooks

Webhooks are the standard way for SIVO to send you events in real time: new calls, transcripts, agents changing status, etc. Your endpoint receives them via HTTP POST and processes them however you want.

Available events

Event	When it fires
call.created	New call (inbound or outbound).
call.answered	Agent accepts.
call.transferred	Transfer (blind, attended or 3-way).
call.ended	Hangup. Includes full CDR.
call.recorded	Recording available with pre-signed URL.
transcript.segment	Live transcript segment.
transcript.completed	Final consolidated transcript.
queue.entered	Call enters ACD queue.
queue.abandoned	Caller hangs up before being answered.
agent.status_changed	Available / On Call / On Break / Logged Out.
agent.paused	Pause with reason.
ivr.completed	IVR flow completed with captured variables.
ai_agent.completed	AI conversation finished with summary.

Configuration

1. Settings → Webhooks → + New endpoint.
2. Fill in:
   • URL: your HTTPS endpoint (plain HTTP not accepted).
   • Subscribed events: tick only what you care about.
   • HMAC secret: SIVO generates one or you set yours.
3. Save. SIVO sends a webhook.test event automatically to verify connectivity.

You can have multiple endpoints per tenant — one for your CRM, another for BI, another for Slack, etc.

Event structure

{
  "id": "evt_01H8XYZ...",
  "type": "call.ended",
  "createdAt": "2026-05-20T10:23:45.123Z",
  "tenantId": "uuid-tenant",
  "data": {
    "callId": "uuid-call",
    "direction": "inbound",
    "from": "+34611222333",
    "to": "+34911234567",
    "duration_sec": 184,
    "agentId": "uuid-agent",
    "queueId": "uuid-queue",
    "mosScore": 4.3,
    "hangupCause": "NORMAL_CLEARING"
  }
}

Headers SIVO sends:

Header	Value	Purpose
X-Sivo-Event-Id	evt_01H8XYZ...	Idempotency. If you receive the same ID twice, discard.
X-Sivo-Event-Type	call.ended	Quick routing without parsing JSON.
X-Sivo-Signature	sha256=<hex>	HMAC signature of body with your secret.
Content-Type	application/json

Signature verification

Each request carries an HMAC SHA-256 signature computed over the raw body with your secret. How to verify in Node.js:

const crypto = require('crypto');

app.post('/webhooks/sivo', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-sivo-signature'];
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

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

  const event = JSON.parse(req.body.toString());
  // Process the event...
  res.status(200).send('ok');
});

Retries with exponential backoff

If your endpoint returns non-2xx status, SIVO retries up to 6 times:

Attempt	Wait after previous
1	immediate
2	5 seconds
3	30 seconds
4	2 minutes
5	10 minutes
6	1 hour
(after)	to dead-letter queue

After the sixth failure, the event moves to the DLQ (Dead Letter Queue) visible in the dashboard. You can:

• Retry manually from the panel.
• Download the event as JSON for inspection.
• Delete if no longer relevant.

DLQ retention: 30 days.

Idempotency

Assume you might receive the same event more than once (timeout on your side, for example). Use X-Sivo-Event-Id as idempotency key. SIVO never changes the ID on retry.

Built-in tester

In Settings → Webhooks → your endpoint → Test, you can:

• Fire a synthetic event of the type you pick.
• View last 100 deliveries with status, latency and body.
• Manually resend a failed event.

Limits

• Max body: 256 KB.
• Timeout: 10 seconds. If your endpoint is slower, it counts as failure. Better to queue internally and respond 200 immediately.
• HTTPS only.
• No redirects — SIVO doesn’t follow 3xx.

Best practices

1. Return 200 ASAP and process async in an internal queue.
2. Always verify the signature — don’t trust headers.
3. Log X-Sivo-Event-Id to correlate with SIVO on incidents.
4. Don’t process events in arrival order — retries can alter order. Use createdAt or per-resource sequences.
5. Reuse connections — establishing TLS per request adds significant latency.