Eventos das chamadas (webhook)

O SendApp pode avisar o seu sistema quando uma chamada começa, termina, passa a uma pessoa ou quando quem liga pede para ser contactado. Ativa-se em Agenda → Webhook: escolha o endereço e assinale os eventos da Voice AI. Cada evento chega num pedido POST assinado, como os eventos das reservas.

Os eventos da Voice AI só chegam se os assinalou: um webhook criado antes, ou sem eventos escolhidos, continua a receber só as reservas.

O corpo é {event, occurred_at, account_ref, call, delivery_id}: call tem os mesmos campos de GET /api/voice/calls/{call_id}, sem transcrição. account_ref identifica a conta e não é uma chave: o corpo nunca contém a sua chave API.

voice.call.ended é a fotografia da chamada no momento em que termina: o resumo da IA e a categoria chegam depois, por isso leia-os em GET /api/voice/calls/{call_id}. O estado da chamada de retorno chega com voice.callback.requested. Cada evento é enviado uma só vez por chamada.

Verifique a assinatura: o header X-SendApp-Signature vale t=<timestamp>,v1=<HMAC-SHA256 de "timestamp.corpo"> com a chave secreta do webhook. Responda com um código 2xx: caso contrário tentamos de novo após 1, 5 e 30 minutos.

Parâmetros

4 · 0 obrigatórios

voice.call.started opcional

Uma chamada começou.

voice.call.ended opcional

Uma chamada terminou: com resultado, duração e resumo.

voice.call.escalated opcional

A IA passou a chamada a uma pessoa.

voice.callback.requested opcional

Quem ligou pede para ser contactado de volta.

Precisa de ajuda com a integração? info@sendapp.live

Pedido

# Exemplo de evento recebido pelo seu servidor
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
// Verifique a assinatura
$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);

// Verifique a assinatura (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);
});

Resposta

{
  "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"
}