webhooks de voz
Webhook de URA: cada chamada de voz vira evento no seu backend
O webhook de URA entrega ao seu SaaS o ciclo completo de cada chamada de voz, do início ao encerramento, com a tecla pressionada, o tempo falado e a causa em português, num endpoint único por conta.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Um endpoint para toda a voz
Ligações únicas, campanhas e ligações ao vivo entregam os eventos no mesmo webhook de conta do canal voice.
Envelope previsível
Todos os eventos usam event, channel, data e timestamp, com os campos que não se aplicam vindo como null.
Assinatura HMAC-SHA256
Com um secret configurado, cada requisição traz X-DAPI-Signature calculada sobre o corpo bruto.
Entrega com retentativa
Fila durável, retentativas automáticas, circuit breaker por URL e logs de cada entrega.
O webhook de URA é onde a ligação deixa de ser um disparo e vira dado de produto. Cada chamada de voz que o seu SaaS faz pela D-API gera eventos que chegam ao seu backend: a ligação começou, alguém atendeu, uma tecla foi pressionada, a ligação terminou e por quê. Com esse webhook de URA bem tratado, a agenda do seu cliente se atualiza sozinha, a régua de cobrança sabe quem ouviu o aviso e a tela de campanha mostra resultado em tempo real.
Esta página cobre o envelope, os eventos, os códigos de causa e o código que o seu endpoint precisa ter para ser seguro e idempotente. Os disparos que geram esses eventos estão no hub de API de URA.
Um webhook de conta para toda a voz
O webhook de voz é configurado uma vez por conta, no painel, no canal voice. Todos os eventos de voz da conta vão para esse mesmo endpoint, venham de uma ligação telefônica por API, de um disparo de voz em massa ou de uma ligação ao vivo. No painel você pode restringir quais eventos o endpoint recebe; sem restrição, chegam todos.
Isso simplifica a infraestrutura: um endpoint, um secret, uma fila de processamento. A contrapartida é que a separação por cliente do seu SaaS acontece no seu banco, com o callId como chave.
Os eventos do ciclo de vida
| Evento | Quando dispara | Campos que importam |
|---|---|---|
call.started |
A ligação foi iniciada | callId, bulkCallId, to |
call.answered |
Alguém atendeu | answered: true |
call.dtmf |
Uma tecla foi pressionada (um evento por tecla) | digits |
call.ended |
A ligação encerrou | answered, talkSeconds, cause, causeDescription |
call.audio |
A gravação de uma ligação ao vivo foi enviada | files, url, durationMs |
Todos usam o mesmo envelope, com event, channel: "voice", data e timestamp no nível raiz. Dentro de data, os campos que não se aplicam ao evento vêm como null, então um único tipo no seu código cobre os quatro eventos do ciclo. Este é um call.dtmf de uma confirmação de consulta:
{
"event": "call.dtmf",
"channel": "voice",
"data": {
"callId": "...",
"bulkCallId": "...",
"to": "+5511999999999",
"answered": null,
"talkSeconds": null,
"digits": "1",
"cause": null,
"causeDescription": null,
"timestamp": "2026-01-24T23:00:20.000Z"
},
"timestamp": "2026-01-24T23:00:20.000Z"
}
O callId é o identificador devolvido no disparo: o bulkId numa campanha ou o callId de uma ligação única ou ao vivo. O bulkCallId separa cada ligação dentro de uma campanha e vem sempre null nas ligações ao vivo. Os eventos call.dtmf só aparecem quando a ligação executa um fluxo de URA com menu ou quando a pessoa aperta teclas numa ligação ao vivo.
Lendo o resultado pelo cause
O call.ended traz cause, que segue os códigos Q.850 da telefonia com dois códigos próprios: 150 (não atendeu, tempo de toque esgotado) e 151 (caixa postal ou secretária eletrônica). O causeDescription já vem em português, e um código sem descrição mapeada aparece como Causa <n>. Os mais comuns:
cause |
Significado | O que o seu produto pode fazer |
|---|---|---|
16 |
Encerramento normal | Marcar como atendida e ouvida |
17 |
Ocupado | Agendar nova ligação em outro horário |
19, 150 |
Não atendeu | Mandar WhatsApp ou SMS de reforço |
151 |
Caixa postal | Enviar o aviso por texto |
1, 28 |
Número inexistente ou inválido | Marcar o contato para revisão |
34, 41, 42 |
Sem canal, falha temporária, congestionamento | Tratar como falha técnica |
Nas ligações ao vivo, cause e causeDescription vêm null. O motivo do encerramento chega pelo reason do WebSocket, e o call.ended traz answered e talkSeconds com os valores efetivamente cobrados. Numa campanha com maxAttempts, uma falha técnica pode gerar uma nova tentativa para o mesmo número; nesse caso chega mais de um call.ended para aquele destinatário, e o que vale como resultado é o último.
Um endpoint seguro e idempotente
Cada requisição chega com Content-Type: application/json, o header X-DAPI-Webhook-Channel: voice e, quando há secret configurado, X-DAPI-Signature com o HMAC-SHA256 em hexadecimal do corpo bruto. O ponto que mais gera bug é calcular o HMAC sobre o JSON já parseado e re-serializado: a ordem das chaves e os espaços mudam e a assinatura não bate. Leia o corpo cru.
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/webhooks/dapi-voice", express.raw({ type: "application/json" }), async (req, res) => {
const expected = crypto
.createHmac("sha256", process.env.DAPI_VOICE_SECRET!)
.update(req.body)
.digest("hex");
const received = String(req.header("X-DAPI-Signature") ?? "");
const valid =
received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const evt = JSON.parse(req.body.toString("utf8"));
const key = [evt.event, evt.data.callId, evt.data.bulkCallId, evt.data.digits, evt.data.timestamp].join(":");
await filaInterna.publicar({ key, evt }); // dedupe pela key e processamento fora do request
res.sendStatus(200);
});
A entrega usa fila durável com retentativas, circuit breaker por URL e logs. Isso protege o resultado de uma campanha contra uma instabilidade no seu endpoint, mas também significa que o mesmo evento pode chegar mais de uma vez. A chave composta de event, callId, bulkCallId, digits e timestamp resolve a duplicidade sem perder teclas legítimas repetidas.
Modelando os eventos num SaaS multi-tenant
No momento do disparo, grave uma linha com o callId, o tenant e o objeto de negócio que originou a ligação. Quando o webhook chega, o lookup por callId diz de qual cliente é o evento e qual registro atualizar: a consulta muda para “confirmada” no call.dtmf com digits: "1", a fatura ganha “aviso ouvido” no call.ended com answered: true, o lead recebe a gravação no call.audio.
Exemplos por segmento:
- Agendamento:
call.dtmfcom1confirma, com2abre a remarcação por WhatsApp, ecall.endedsem atendimento coloca o paciente na fila de lembrete por SMS. - Cobrança:
call.endedcomtalkSecondsacima da duração do aviso indica que a pessoa ouviu até o fim, e isso entra no score de contato. - CRM:
call.audiotrazfull,sendererecipient, e a ficha do lead guarda o link da mixagem para revisão do gestor.
O mesmo canal voice também recebe eventos dos agentes de voz com IA (voice_agent.call.started e voice_agent.call.ended), com o status, o motivo do encerramento e os dados capturados na conversa; o uso deles está em agente de voz com IA para telefone. O padrão de envelope é o mesmo do webhook de SMS, então o seu roteador de eventos pode tratar os dois canais com o mesmo código de assinatura. A tabela completa de causas e os exemplos de cada evento estão na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
Onde configuro o webhook de URA?
No painel da D-API, uma vez por conta, no canal voice. Você informa a URL, o secret de assinatura e, se quiser, a lista de eventos que o endpoint deve receber. Sem restrição, todos os eventos do canal são entregues.
Posso ter um webhook de voz por cliente do meu SaaS?
O webhook de voz é um por conta. Para separar por cliente, grave o callId retornado no disparo junto com o identificador do tenant e resolva o dono do evento por esse campo quando ele chegar.
Por que recebo call.dtmf separado para cada tecla?
Cada tecla gera um webhook, com digits contendo um único caractere de 0 a 9, asterisco ou cerquilha. Para capturar um código de vários dígitos, acumule os eventos por callId e bulkCallId na ordem do timestamp.
O que significa cause 151?
É um código próprio da D-API para caixa postal ou secretária eletrônica. O outro código próprio é o 150, tempo de toque esgotado. Os demais seguem a tabela Q.850, com descrição em português no campo causeDescription.
Quanto tempo meu endpoint tem para responder?
Responda o mais rápido possível com status 2xx e processe o evento depois, numa fila sua. Falhas temporárias são reenviadas automaticamente, e o circuit breaker por URL protege o seu endpoint de uma enxurrada de reenvios.