Skip to main content

​
O que é um webhook

Um webhook é uma forma do IPBoX avisar automaticamente um sistema seu quando algo acontece — por exemplo, quando um agente faz login, entra em pausa, ou atende uma ligação. Em vez de você ficar consultando a API de tempos em tempos para saber se algo mudou, o IPBoX envia essa informação para uma URL sua, assim que o evento acontece. É a mesma ideia usada por diversos sistemas de mercado (CRMs, gateways de pagamento, etc.): você cadastra uma URL, escolhe quais eventos quer receber, e passa a receber um POST em JSON toda vez que algum deles acontecer. Repare que quem inicia a chamada é sempre o IPBoX — você não precisa ficar perguntando “mudou alguma coisa?” de tempos em tempos, é o contrário: o IPBoX avisa assim que muda.

​
Como cadastrar um webhook

  1. No IPBoX, acesse IPBoX > Integrações > Webhook.
  2. Clique em Inserir.
  3. Preencha:
    • Descrição: um nome pra você identificar esse webhook depois (ex.: “Notificação para o meu CRM”).
    • URL: o endereço do seu sistema que vai receber as notificações (precisa começar com http:// ou https://).
    • Secret (opcional): uma senha que só você e seu sistema conhecem, usada para confirmar que a chamada realmente veio do IPBoX (veja detalhes na referência técnica).
    • Eventos: marque quais eventos você quer receber. Dá pra marcar um por um, ou usar o “Selecionar todos” no topo de cada grupo.
  4. Clique em Salvar.
Pronto — a partir daí, toda vez que um dos eventos marcados acontecer, o IPBoX envia uma notificação para a sua URL, em tempo real (assim que o evento acontece, sem atraso de minutos).

​
Quais eventos existem hoje

Os eventos são organizados em dois grupos: agente e ligação.

​
Eventos de agente

Acompanham o estado de cada agente no painel:

​
Eventos de ligação

Acompanham cada ligação (entrante, sainte ou interna; feita pelo softphone/webphone, pelo discador ou pela API): Os campos de cada evento de ligação estão explicados na referência técnica.
Novas categorias de eventos aparecem automaticamente como um novo grupo na mesma tela, sem precisar de nenhuma configuração extra da sua parte.

​
Testando seu webhook

Antes de conectar no seu sistema de verdade, você pode testar com uma ferramenta gratuita chamada webhook.site:
  1. Acesse webhook.site — ele já gera uma URL única na hora, algo como https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.
  2. Copie essa URL e cole no campo URL do cadastro do webhook no IPBoX.
  3. Marque pelo menos um evento (ex.: “Login”) e salve.
  4. Faça login com um agente de teste no painel do IPBoX.
  5. Volte na aba do webhook.site — você deve ver a chamada chegando ali, com o corpo (JSON) e os headers da requisição.
Se a chamada não aparecer, confira se a URL foi digitada corretamente e se o evento que você testou está marcado no cadastro.

​
Próximos passos

Se você vai integrar o webhook no seu próprio sistema (não só testar), veja a Referência técnica do Webhook — lá tem o formato exato do JSON de cada evento, os headers enviados, e exemplos de código para validar as chamadas. Para ver um exemplo completo (webphone + CRM), veja o guia Exemplo de integração: webphone + CRM.