Eventi delle chiamate (webhook)

SendApp può avvisare il tuo sistema quando una chiamata inizia, finisce, passa a una persona o quando chi chiama chiede di essere richiamato. Si attiva da Agenda → Webhook: scegli l'indirizzo e spunta gli eventi della Voice AI. Ogni evento arriva con una richiesta POST firmata, come gli eventi delle prenotazioni.

Gli eventi della Voice AI arrivano solo se li hai spuntati: un webhook creato prima, o senza eventi scelti, continua a ricevere solo le prenotazioni.

Il corpo è {event, occurred_at, account_ref, call, delivery_id}: call ha gli stessi campi di GET /api/voice/calls/{call_id}, senza trascritto. account_ref identifica l'account e non è una chiave: il corpo non contiene mai la tua chiave API.

voice.call.ended è la fotografia della chiamata nel momento in cui finisce: il riassunto AI e la categoria arrivano dopo, quindi leggili da GET /api/voice/calls/{call_id}. Lo stato della richiamata arriva con voice.callback.requested. Ogni evento parte una sola volta per chiamata.

Verifica la firma: l'header X-SendApp-Signature vale t=<timestamp>,v1=<HMAC-SHA256 di "timestamp.corpo"> con la chiave segreta del webhook. Rispondi con un codice 2xx: altrimenti riproviamo dopo 1, 5 e 30 minuti.

Parametri

4 · 0 obbligatori

voice.call.started opzionale

Una chiamata è iniziata.

voice.call.ended opzionale

Una chiamata è finita: con esito, durata e riassunto.

voice.call.escalated opzionale

L'AI ha passato la chiamata a una persona.

voice.callback.requested opzionale

Chi ha chiamato chiede di essere richiamato.

Serve aiuto con l'integrazione? info@sendapp.live

Richiesta

# Esempio di evento ricevuto dal tuo server
POST /hooks/sendapp HTTP/1.1
Content-Type: application/json
X-SendApp-Event: voice.call.ended
X-SendApp-Delivery: 5d0c2a4e-7b1f-4c3a-9e2d-8f6a1b2c3d4e
X-SendApp-Signature: t=1793870101,v1=6f1d0c…

<?php
// Verifica la firma
$body = file_get_contents('php://input');
$secret = 'whsec_...';
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SENDAPP_SIGNATURE'] ?? ''), $sig);
$ok = isset($sig['t'], $sig['v1'])
    && abs(time() - (int) $sig['t']) < 300
    && hash_equals(hash_hmac('sha256', $sig['t'] . '.' . $body, $secret), $sig['v1']);
if (!$ok) { http_response_code(400); exit; }
$event = json_decode($body, true);
http_response_code(200);

// Verifica la firma (Node.js, Express)
const crypto = require('crypto');
app.post('/hooks/sendapp', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries(String(req.get('X-SendApp-Signature')).split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', process.env.SENDAPP_SECRET)
    .update(sig.t + '.' + req.body).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(String(sig.v1 || ''));
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

Risposta

{
  "event": "voice.call.ended",
  "occurred_at": "2026-11-05T09:15:01Z",
  "account_ref": "acct_9f3c2a7e5b1d4c6f",
  "call": {
    "call_id": "1789749582.1320",
    "direction": "in",
    "status": "answered",
    "from_number": "+393331234567",
    "to_number": "+390212345678",
    "assistant_id": "YOUR_ACCOUNT_TOKEN",
    "ai_handled": true,
    "ai_escalated": false,
    "started_at": "2026-11-05T09:12:04Z",
    "answered_at": "2026-11-05T09:12:06Z",
    "ended_at": "2026-11-05T09:15:01Z",
    "wait_seconds": 2,
    "talk_seconds": 175,
    "end_reason": "completed",
    "disposition": null,
    "disposition_note": null,
    "ai_summary": null,
    "summary": null,
    "category": null,
    "sentiment": null,
    "callback_status": null,
    "callback_at": null,
    "conversation_id": "9b2f4c1e-8a5d-4f7b-9c3e-1d2a3b4c5d6e",
    "has_voicemail": false,
    "voicemail_seconds": null,
    "recording_available": true,
    "recording_seconds": 173,
    "recording_expires_at": "2026-12-05T09:15:01Z"
  },
  "delivery_id": "5d0c2a4e-7b1f-4c3a-9e2d-8f6a1b2c3d4e"
}