Referência técnica do Webhook

Se você ainda não sabe o que é ou como cadastrar um webhook, veja primeiro o guia de Webhooks.

Visão geral

Método: POST
Content-Type: application/json
Entrega: em tempo real — assim que o evento acontece no IPBoX
Tentativas: timeout de 5 segundos por chamada. Seu endpoint precisa responder rápido e com um status 2xx para confirmar o recebimento.
- Eventos de agente (agente.*): uma única tentativa, sem retry automático.
- Eventos de ligação (ligacao.*): até 5 tentativas no total, com intervalos crescentes (5s, 15s, 1min e 5min) quando a resposta não for 2xx. Veja Entrega e reenvio.

Headers enviados

Header	Sempre enviado?	Descrição
`Content-Type`	Sim	Sempre `application/json`
`X-Webhook-Event-Id`	Só nos eventos de ligação	Mesmo valor do campo `evento_id` do payload — use para descartar duplicados
`X-Webhook-Secret`	Só se configurado	Valor exato do campo Secret cadastrado no webhook — veja Validando a origem da chamada

Formato do payload

Os eventos de agente (agente.*) e os de ligação (ligacao.*) têm formatos diferentes. Esta seção descreve os de agente; os de ligação estão em Eventos de ligação. Todo evento de agente chega com esse formato base:

{
  "estado": "string",
  "t": 1725650000,
  "evento": "agente.login",
  "usuario_id": 42
}

estado: estado interno do agente no momento do evento (online, offline, paused, busy ou ringing)
t: timestamp Unix (segundos) de quando o evento foi gerado
evento: código do evento — é este campo que você usa para saber qual dos eventos marcados no cadastro está chegando
usuario_id: ID do agente no IPBoX

Alguns eventos trazem campos extras, além desses quatro (ver tabela abaixo).

Catálogo de eventos de agente

Código (`evento`)	Quando dispara	Campos extras no payload
`agente.login`	Agente faz login	—
`agente.logout`	Agente faz logout	—
`agente.pause_in`	Agente entra em pausa	`pausa_id`, `udate`, e opcionalmente `durmax`/`durmin` (limites de duração da pausa, em segundos, quando configurados)
`agente.pause_out`	Agente sai da pausa	— (`estado` pode vir `online` ou `busy`, dependendo se o agente já tinha uma ligação em andamento)
`agente.busy`	Agente entra em uma ligação	`udate`, `login`, `ramal`, `numero`, `uid1`, `codigo`, `fila_id`, `lote_id` (veja campos extras do `agente.busy`)
`agente.ringing`	Telefone do agente está tocando	—
`agente.online`	Ligação terminou / agente disponível de novo	—

Campos extras do `agente.busy`

Campo	Tipo	Descrição
`udate`	inteiro	Timestamp Unix (segundos) de quando a ligação começou
`login`	string	Login do agente
`ramal`	string	Ramal em que o agente está atendendo. Vazio se não for possível identificar
`numero`	string	Telefone do cliente na ligação (apenas dígitos, quando possível)
`uid1`	string	Identificador (`uniqueid`) da ligação na central telefônica
`codigo`	string	Código do prospect, quando a ligação está associada a um prospect (ex.: discador). Vazio nas demais
`fila_id`	inteiro \| string vazia	ID da fila da ligação. Vazio quando não passou por fila
`lote_id`	inteiro \| string vazia	ID do lote do prospect. Vazio quando a ligação não está associada a um lote

Os campos que não se aplicam à ligação vêm como string vazia (""), não null.

Exemplos de payload

agente.logout

{
  "estado": "offline",
  "t": 1725650500,
  "evento": "agente.logout",
  "usuario_id": 42
}

agente.pause_in

{
  "estado": "paused",
  "t": 1725650100,
  "pausa_id": 3,
  "udate": 1725650100,
  "durmax": 900,
  "evento": "agente.pause_in",
  "usuario_id": 42
}

agente.pause_out

{
  "estado": "online",
  "t": 1725650300,
  "evento": "agente.pause_out",
  "usuario_id": 42
}

agente.busy

{
  "estado": "busy",
  "t": 1725650200,
  "udate": 1725650200,
  "evento": "agente.busy",
  "usuario_id": 42,
  "login": "agente08",
  "ramal": "2000",
  "numero": "11992626326",
  "uid1": "ipbox-srv01-1725650195.31",
  "codigo": "CLI-1042",
  "fila_id": 51,
  "lote_id": 7
}

agente.ringing

{
  "estado": "ringing",
  "t": 1725650250,
  "evento": "agente.ringing",
  "usuario_id": 42
}

agente.online

{
  "estado": "online",
  "t": 1725650400,
  "evento": "agente.online",
  "usuario_id": 42
}

Eventos de ligação

Os eventos ligacao.* acompanham o ciclo de vida de cada ligação do IPBoX: entrantes, saintes e internas (entre ramais), feitas pelo softphone/webphone, pelo discador ou pela API de click-to-call.

Catálogo

Código (`evento`)	Quando dispara
`ligacao.recebida`	Uma ligação entrante chegou ao IPBoX (antes de URA, fila ou toque em qualquer ramal)
`ligacao.discando`	A ligação começou a ser discada: a chamada saiu do ramal/discador/API, ou, numa entrante, o IPBoX começou a chamar um ramal. Pode ocorrer mais de uma vez na mesma ligação (uma por tentativa)
`ligacao.tocando`	O destino está tocando
`ligacao.atendida`	A ligação foi atendida
`ligacao.conectada`	Um agente entrou na ligação vinda de uma fila (no discador, o cliente atende primeiro e o agente é conectado depois)
`ligacao.abandonada`	O chamador desistiu enquanto esperava na fila, sem ser atendido por um agente
`ligacao.falha`	A ligação terminou sem ser atendida (ocupado, não atende, indisponível etc.). Sempre vem antes do `ligacao.encerrada`
`ligacao.encerrada`	A ligação terminou. É emitido uma vez por ligação, sempre por último, e traz o resumo final

Sequências típicas:

Cenário	Eventos, em ordem
Entrante direta atendida	`recebida` → `discando` → `tocando` → `atendida` → `encerrada`
Entrante via fila atendida	`recebida` → `discando` → `tocando` → `atendida` → `conectada` → `encerrada`
Entrante abandonada na fila	`recebida` → `abandonada` → `encerrada`
Entrante que desligou na URA (antes de fila ou ramal)	`recebida` → `encerrada` (`resultado: desligada`, `motivo: ura`)
Sainte de ramal atendida	`discando` → `tocando` → `atendida` → `encerrada`
Sainte não atendida (ocupado, não atende…)	`discando` → (`tocando`) → `falha` → `encerrada`
Discador, cliente atende e agente conecta	`discando` → `tocando` → `atendida` → `conectada` → `encerrada`

Nem todo evento aparece em toda ligação (por exemplo, uma ligação que cai antes de tocar não tem tocando). Use sequencia para ordenar e ligacao_id para agrupar.

Campos comuns (todos os eventos de ligação)

Campo	Tipo	Descrição
`evento`	string	Código do evento (ex.: `ligacao.atendida`)
`versao`	inteiro	Versão do formato do payload. Hoje sempre `1`
`evento_id`	string	Identificador único do evento (hash SHA-256). É determinístico: se o mesmo evento for reenviado, o `evento_id` é o mesmo — use para ignorar duplicados. Também enviado no header `X-Webhook-Event-Id`
`ligacao_id`	string	Identificador da ligação no webhook. Todos os eventos da mesma ligação têm o mesmo valor
`sequencia`	inteiro	Ordem do evento dentro da ligação, começando em `1`. Use para ordenar eventos que cheguem fora de ordem
`ocorrido_em`	string	Momento em que o evento aconteceu, em UTC, formato ISO 8601 (`2026-10-22T14:38:18Z`). Nos eventos `falha`/`encerrada` é o momento em que o último canal da ligação desligou
`direcao`	string	`entrante` (chegou de fora), `sainte` (saiu para um número externo) ou `interna` (entre dois ramais)
`origem`	string	Quem iniciou a ligação: `externa` (entrante vinda da operadora), `ramal` (agente discando pelo softphone/webphone), `discador` (discador automático) ou `api` (click-to-call pela API)
`numero_origem`	string \| null	Número de quem originou a ligação (ex.: número do cliente em uma entrante, ramal em uma sainte)
`numero_destino`	string \| null	Número discado/chamado (ex.: o número externo em uma sainte, ou o número da operadora que o cliente ligou em uma entrante)
`ramal`	string \| null	Ramal do agente envolvido na ligação. Em saintes de ramal, o ramal que discou; em entrantes, o ramal que está sendo chamado/que atendeu. `null` enquanto ainda não se sabe (ex.: `recebida`, ou ligação do discador antes de o agente ser conectado)
`usuario_id`	inteiro \| null	ID do agente (usuário) logado no `ramal`, o mesmo `usuario_id` dos eventos de agente. `null` quando não há agente conhecido
`fila`	string \| null	Código da fila por onde a ligação passou. `null` se não passou por fila (ainda)
`prospect_id`	inteiro \| null	ID do prospect (cliente) no discador. Só em ligações do discador
`numero_id`	inteiro \| null	ID do número discado na campanha do discador. Só em ligações do discador
`action_id`	string \| null	Identificador da requisição de discagem (discador/API). No discador é o mesmo valor de `numero_id`; na API de click-to-call tem o formato `usuarioId\|numero`. `null` em ligações que não foram originadas pelo IPBoX
`linkedid`	string \| null	Identificador da ligação na central telefônica (Asterisk). Comum a todos os canais da ligação
`uniqueid`	string \| null	Identificador do canal inicial da ligação (o primeiro canal criado)
`uniqueids`	array de string	Todos os canais conhecidos da ligação até aquele evento (inclui o `uniqueid`). Cresce ao longo da ligação, por exemplo quando um ramal é chamado. Útil para cruzar com o CDR e com a gravação

Campos específicos por evento

ligacao.discando

Campo	Tipo	Descrição
`tentativa_id`	string	Identifica a tentativa de discagem, no formato `uniqueid_origem>uniqueid_destino`. Em uma entrante que toca em vários ramais em sequência, cada ramal chamado gera um `discando` com `tentativa_id` diferente. Não vem no `discando` de ligações do discador/API

ligacao.tocando

Sem campos extras.

ligacao.atendida

Campo	Tipo	Descrição
`atendida_por`	string	Quem atendeu: `ramal` (um ramal/agente, em entrante ou interna), `destino_externo` (o número externo atendeu uma ligação sainte) ou `agente` (agente conectado a partir de uma fila)

No discador, o atendida marca o cliente atendendo e normalmente ainda não traz ramal/usuario_id: eles chegam em seguida no ligacao.conectada.

ligacao.conectada

Campo	Tipo	Descrição
`tempo_espera`	inteiro	Segundos que o chamador esperou na fila até ser conectado ao agente

Aqui ramal e usuario_id identificam o agente que foi conectado.

ligacao.abandonada

Campo	Tipo	Descrição
`tempo_espera`	inteiro	Segundos que o chamador esperou na fila antes de desistir
`posicao`	inteiro	Posição do chamador na fila quando desistiu

ligacao.falha e ligacao.encerrada

Os dois eventos trazem o mesmo conjunto de campos de resumo; o ligacao.encerrada tem ainda o gravacao_url.

Campo	Tipo	Descrição
`resultado`	string	Como a ligação terminou: `atendida`, `abandonada` (desistiu na fila), `desligada` (entrante desligada na URA), `falha` (nunca foi atendida) ou `desconhecido` (veja `reconciliada`)
`motivo`	string	Detalha o `resultado`. Quando `resultado` é `desligada`, vale `ura`: o cliente desligou na URA, antes de qualquer fila ou ramal (nesse caso não há `ligacao.falha` nem `ligacao.abandonada`). Quando `resultado` é `falha`, é a causa: `ocupado`, `nao_atende`, `cancelada` (quem ligou desistiu antes de atender), `indisponivel` (destino fora do ar/inexistente), `congestionamento`, `erro_originacao` (o IPBoX não conseguiu iniciar a discagem) ou `nao_completada` (nenhuma das anteriores). Nos demais casos repete o valor de `resultado`
`originate_reason`	string \| null	Código de motivo informado quando o IPBoX não conseguiu originar a ligação (discador/API). `null` nos demais casos
`duracao`	inteiro	Duração total da ligação, em segundos, da criação até o último desligamento (inclui o tempo de toque e de fila)
`duracao_atendida`	inteiro	Segundos entre o atendimento e o desligamento (tempo de conversa). `0` se não foi atendida
`reconciliada`	booleano	`true` quando o IPBoX não recebeu o desligamento da ligação e a encerrou ao perceber, na verificação periódica, que ela não existia mais na central (por exemplo, após reinício do serviço). Nesse caso `resultado` é `desconhecido`, não há `ligacao.falha`, e `ocorrido_em` é o momento da verificação, não do desligamento real
`gravacao_url`	string \| null	Só no `ligacao.encerrada`. URL para baixar a gravação da ligação, quando existe. `null` se a ligação não foi gravada

O ligacao.falha só é emitido quando resultado é falha. O ligacao.encerrada é emitido sempre.Para ligações atendidas, o ligacao.encerrada pode ser enviado até cerca de 6 segundos após o desligamento, para aguardar o registro da gravação e poder trazer o gravacao_url.

Exemplos de payload

Nos exemplos, evento_id aparece abreviado como … e, a partir do segundo exemplo, alguns campos comuns (linkedid, uniqueid, uniqueids, prospect_id, numero_id, action_id) foram omitidos para encurtar. No payload real, todos os campos comuns sempre vêm.

ligacao.recebida

{
  "evento": "ligacao.recebida",
  "direcao": "entrante",
  "origem": "externa",
  "linkedid": "ipbox-srv01-1792679878.51",
  "uniqueid": "ipbox-srv01-1792679878.51",
  "numero_origem": "551122198774",
  "numero_destino": "551122331132",
  "ramal": null,
  "usuario_id": null,
  "fila": null,
  "prospect_id": null,
  "numero_id": null,
  "action_id": null,
  "versao": 1,
  "evento_id": "7cc9a5d43f6097c4f53a078ce814671e39b189976c8a4d7a5ba5655d6dc74bf4",
  "ligacao_id": "9b5d91df25d1e564db23ec4e6ae05a8b",
  "uniqueids": ["ipbox-srv01-1792679878.51"],
  "sequencia": 1,
  "ocorrido_em": "2026-10-22T14:37:58Z"
}

ligacao.discando (entrante chamando um ramal)

{
  "evento": "ligacao.discando",
  "direcao": "entrante",
  "origem": "externa",
  "linkedid": "ipbox-srv01-1792679878.51",
  "uniqueid": "ipbox-srv01-1792679878.51",
  "numero_origem": "551122198774",
  "numero_destino": "551122331132",
  "ramal": "6138",
  "usuario_id": 188,
  "fila": "00022",
  "prospect_id": null,
  "numero_id": null,
  "action_id": null,
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "9b5d91df25d1e564db23ec4e6ae05a8b",
  "uniqueids": ["ipbox-srv01-1792679878.51", "ipbox-srv01-1792679898.54"],
  "sequencia": 2,
  "ocorrido_em": "2026-10-22T14:38:18Z",
  "tentativa_id": "ipbox-srv01-1792679878.51>ipbox-srv01-1792679898.54"
}

ligacao.atendida

{
  "evento": "ligacao.atendida",
  "direcao": "entrante",
  "origem": "externa",
  "ramal": "6138",
  "usuario_id": 188,
  "fila": "00022",
  "numero_origem": "551122198774",
  "numero_destino": "551122331132",
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "9b5d91df25d1e564db23ec4e6ae05a8b",
  "sequencia": 4,
  "ocorrido_em": "2026-10-22T14:38:25Z",
  "atendida_por": "agente"
}

ligacao.conectada

{
  "evento": "ligacao.conectada",
  "direcao": "sainte",
  "origem": "discador",
  "ramal": "6138",
  "usuario_id": 188,
  "fila": "00051",
  "prospect_id": 5521,
  "numero_id": 943885,
  "action_id": "943885",
  "numero_origem": "11999990000",
  "numero_destino": "11992626326",
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "…",
  "sequencia": 4,
  "ocorrido_em": "2026-10-22T16:26:12Z",
  "tempo_espera": 2
}

ligacao.abandonada

{
  "evento": "ligacao.abandonada",
  "direcao": "entrante",
  "origem": "externa",
  "ramal": null,
  "usuario_id": null,
  "fila": "00022",
  "numero_origem": "551122198774",
  "numero_destino": "551122331132",
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "…",
  "sequencia": 2,
  "ocorrido_em": "2026-10-22T14:40:03Z",
  "tempo_espera": 18,
  "posicao": 1
}

ligacao.falha

{
  "evento": "ligacao.falha",
  "direcao": "sainte",
  "origem": "ramal",
  "ramal": "6138",
  "usuario_id": 188,
  "numero_origem": "6138",
  "numero_destino": "11992626326",
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "…",
  "sequencia": 3,
  "ocorrido_em": "2026-10-22T15:02:40Z",
  "resultado": "falha",
  "motivo": "ocupado",
  "originate_reason": null,
  "duracao": 6,
  "duracao_atendida": 0,
  "reconciliada": false
}

ligacao.encerrada

{
  "evento": "ligacao.encerrada",
  "direcao": "entrante",
  "origem": "externa",
  "ramal": "6138",
  "usuario_id": 188,
  "fila": "00022",
  "numero_origem": "551122198774",
  "numero_destino": "551122331132",
  "versao": 1,
  "evento_id": "…",
  "ligacao_id": "9b5d91df25d1e564db23ec4e6ae05a8b",
  "sequencia": 6,
  "ocorrido_em": "2026-10-22T14:39:30Z",
  "resultado": "atendida",
  "motivo": "atendida",
  "originate_reason": null,
  "duracao": 92,
  "duracao_atendida": 65,
  "reconciliada": false,
  "gravacao_url": "https://exemplo.ipbox.com.br/ipbox/monitor/fila/00022/2026/10/22/…WAV"
}

Entrega e reenvio dos eventos de ligação

Cada evento é enviado a cada webhook que o tenha marcado no cadastro.
Se o seu endpoint responder algo diferente de 2xx, der timeout (5s) ou ficar indisponível, o IPBoX reenvia somente para aquele webhook, até 5 tentativas no total, com intervalos de 5s, 15s, 1min e 5min. Depois disso o evento é descartado.
No reenvio o payload e o evento_id são idênticos aos do primeiro envio. Como o endpoint pode ter processado o evento e falhado só ao responder, trate o evento_id como chave de idempotência.
Por causa dos reenvios, os eventos de uma mesma ligação podem chegar fora de ordem. Ordene por sequencia.
O ocorrido_em é a hora real do evento, não a hora da entrega.

Sempre responda rápido com 2xx e processe em segundo plano. Respostas lentas ou com erro geram reenvios e duplicidade.

Webhook que falha sempre é suspenso. Depois de 20 falhas de envio seguidas, o envio é suspenso e o webhook deixa de receber eventos. Uma resposta 2xx zera a contagem. No cadastro de webhooks, ele continua listado, com a situação Suspenso por falhas e a data. Corrija o endpoint, abra o webhook e salve com a opção Reativar o envio ao salvar marcada. Os reenvios de cada evento contam como falhas, então uma URL fora do ar chega ao limite em poucos eventos.

Validando a origem da chamada

Se você preencher o campo Secret no cadastro do webhook, toda chamada chega com o header X-Webhook-Secret contendo exatamente esse valor. Compare o header recebido com o valor que você configurou — se não bater, rejeite a chamada.

Esse mecanismo é um segredo compartilhado simples (o mesmo valor vai em todas as chamadas), não uma assinatura criptográfica do corpo da requisição (tipo HMAC). Ele protege contra chamadas de quem não conhece o secret, mas não garante que o corpo da requisição não foi alterado em trânsito. Use sempre uma URL HTTPS para evitar que o secret trafegue em texto puro numa rede não confiável.

Exemplo em PHP

<?php
$payload = file_get_contents('php://input');
$secretRecebido = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';

if ($secretRecebido !== 'SEU_SECRET_AQUI') {
    http_response_code(401);
    exit;
}

$data = json_decode($payload, true);

// $data['evento'], $data['usuario_id'], $data['estado'], $data['t']
// ... seu processamento aqui ...

http_response_code(200);

Exemplo com curl (simulando o recebimento)

curl -X POST "https://seusistema.com/webhook-ipbox" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: SEU_SECRET_AQUI" \
  -d '{"estado":"paused","t":1725650000,"evento":"agente.login","usuario_id":42}'

Boas práticas

Responda rápido (idealmente em menos de 1 segundo) e com status 2xx — nos eventos de agente não há retry automático, então uma resposta lenta ou com erro faz você perder aquela notificação (nos de ligação há reenvio, veja acima).
Se precisar processar algo demorado a partir do evento, responda 200 imediatamente e processe de forma assíncrona no seu lado.
Trate o campo evento como a fonte da verdade sobre o que aconteceu — não dependa só do campo estado, já que o mesmo valor de estado pode aparecer em mais de um tipo de evento.

Guias

Webhook - Referência técnica

Referência da API

Referência técnica do Webhook

Visão geral

Headers enviados

Formato do payload

Catálogo de eventos de agente

Campos extras do `agente.busy`

Exemplos de payload

Eventos de ligação

Catálogo

Campos comuns (todos os eventos de ligação)

Campos específicos por evento

Exemplos de payload

Entrega e reenvio dos eventos de ligação

Validando a origem da chamada

Exemplo em PHP

Exemplo com curl (simulando o recebimento)

Boas práticas

​Visão geral

​Headers enviados

​Formato do payload

​Catálogo de eventos de agente

​Campos extras do agente.busy

​Exemplos de payload

​Eventos de ligação

​Catálogo

​Campos comuns (todos os eventos de ligação)

​Campos específicos por evento

​Exemplos de payload

​Entrega e reenvio dos eventos de ligação

​Validando a origem da chamada

​Exemplo em PHP

​Exemplo com curl (simulando o recebimento)

​Boas práticas

Visão geral

Headers enviados

Formato do payload

Catálogo de eventos de agente

Campos extras do `agente.busy`

Exemplos de payload

Eventos de ligação

Catálogo

Campos comuns (todos os eventos de ligação)

Campos específicos por evento

Exemplos de payload

Entrega e reenvio dos eventos de ligação

Validando a origem da chamada

Exemplo em PHP

Exemplo com curl (simulando o recebimento)

Boas práticas