Eventos de webhooks

Na API você pergunta; no webhook a Notifique avisa. Ideal para URA, discador e billing por minuto, sem polling de status.

Em poucas palavras

Toda entrega é um POST application/json para a URL cadastrada.
Chamadas usam voice.call.*, não confunda com message.* (WhatsApp) ou sms.*.
Ciclo do número contratado (phone_number.*) está em Números de telefone, Eventos.
fromE164 e toE164 usam dígitos E.164 sem + (ex.: 5511999887766), igual ao envio na API.
Responda 2xx rápido; processamento pesado vai para fila no seu lado.

Configuração geral: Webhooks. Segurança (assinatura HMAC): Segurança de webhooks.

Como vem o POST

{
  "event": "voice.call.answered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "ANSWERED",
    "clientState": "campanha-42"
  }
}

Campo	Descrição
`event`	Nome do evento (ex.: `voice.call.answered`)
`workspaceId`	ID do workspace
`instanceId`	Sempre vazio em voz
`timestamp`	ISO 8601, use para anti-replay
`data`	Campos da chamada ou do número (camelCase)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id, X-Webhook-Event.

O que seu servidor deve responder

Resposta	Efeito
2xx em até ~10s	Evento entregue; sai da fila
4xx / 5xx / timeout	Retentativa automática (5 min, 30 min, 2 h)

Processamento demorado? Responda 200 logo e processe em background.

Eventos de chamada (`voice.call.*`)

Evento	Quando dispara	O que fazer com isso
`voice.call.initiated`	Discagem de saída iniciada	Log, CRM
`voice.call.received`	Chamada entrante no número	Roteamento / URA
`voice.call.ringing`	Destino tocando	UI de status
`voice.call.answered`	Chamada atendida	Iniciar fluxo, cobrança
`voice.call.completed`	Chamada encerrada	Fechar ticket, billing
`voice.call.failed`	Não completou	Retentar ou alertar
`voice.call.dtmf`	Cliente digitou tecla	Menu interativo
`voice.call.gather.ended`	Coleta DTMF finalizada	Próximo passo da URA
`voice.call.recording.ready`	Gravação disponível	QA, compliance
`voice.call.machine.detected`	Caixa postal detectada	Regra de retentativa

Payload de cada evento de chamada

voice.call.initiated

{
  "event": "voice.call.initiated",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:29:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "INITIATED",
    "clientState": "campanha-42"
  }
}

voice.call.received

Disparado em chamadas inbound. Use com inboundVoiceAction: WEBHOOK_CONTROL no número.

{
  "event": "voice.call.received",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T15:00:00.000Z",
  "data": {
    "callId": "clxx_call_2",
    "direction": "INBOUND",
    "fromE164": "5511999887766",
    "toE164": "5511987654321",
    "status": "RINGING"
  }
}

voice.call.ringing

{
  "event": "voice.call.ringing",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:29:15.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "RINGING"
  }
}

voice.call.answered

{
  "event": "voice.call.answered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "ANSWERED",
    "answeredAt": "2026-06-11T14:30:00.000Z"
  }
}

voice.call.completed

{
  "event": "voice.call.completed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:32:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "COMPLETED",
    "durationSecs": 120,
    "hangupCause": "normal_clearing"
  }
}

voice.call.failed

{
  "event": "voice.call.failed",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:29:45.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "5511987654321",
    "toE164": "5511999887766",
    "status": "FAILED",
    "hangupCause": "no_answer"
  }
}

voice.call.dtmf

{
  "event": "voice.call.dtmf",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:20.000Z",
  "data": {
    "callId": "clxx_call_1",
    "dtmfDigits": "1"
  }
}

voice.call.gather.ended

{
  "event": "voice.call.gather.ended",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:35.000Z",
  "data": {
    "callId": "clxx_call_1",
    "gatherResult": "12345678901"
  }
}

voice.call.recording.ready

{
  "event": "voice.call.recording.ready",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:33:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "recordingId": "clxx_rec_1"
  }
}

voice.call.machine.detected

{
  "event": "voice.call.machine.detected",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:05.000Z",
  "data": {
    "callId": "clxx_call_1",
    "machineDetectionResult": "machine"
  }
}

Webhook por chamada

Além dos webhooks globais do workspace (Webhooks), cada origem pode definir destino próprio:

"options": {
  "webhook": {
    "url": "https://api.suaempresa.com/voice/hooks",
    "secret": "opcional"
  }
}

Quando options.webhook.url está presente, todos os eventos voice.call.* daquela chamada vão apenas para essa URL. Os endpoints cadastrados no workspace não recebem cópia do mesmo evento. Assinatura: header X-Notifique-Signature com secret informado (ou o do webhook global, se não houver override). Detalhes: Eventos dos webhooks — Webhook por chamada.

Inbound com webhook

Quando o número usa inboundVoiceAction: WEBHOOK_CONTROL:

Receba voice.call.received
Controle a sessão com ações na API (speak, gather, transfer, hangup)
Acompanhe voice.call.answered, voice.call.dtmf, voice.call.completed, etc.

Configuração do número: Números de telefone, Quick Start.

Próximos passos

Quick Start: originar e controlar
Introdução: ciclo da chamada
Escopos: permissões da chave
Números de telefone: contratar e configurar linha
Webhooks (guia geral)

Voz

Voice: Chamadas

Voice: Fluxos IVR

Números de telefone

Números de Telefone

Eventos de webhooks

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Eventos de chamada (`voice.call.*`)

Payload de cada evento de chamada

Webhook por chamada

Inbound com webhook

Próximos passos

​Em poucas palavras

​Como vem o POST

​O que seu servidor deve responder

​Eventos de chamada (voice.call.*)

​Payload de cada evento de chamada

​Webhook por chamada

​Inbound com webhook

​Próximos passos

Em poucas palavras

Como vem o POST

O que seu servidor deve responder

Eventos de chamada (`voice.call.*`)

Payload de cada evento de chamada

Webhook por chamada

Inbound com webhook

Próximos passos