> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ipbox.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real quando o estado de um agente muda

## 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.

## 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](/webhooks/referencia-tecnica)).
   * **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

| Evento                      | Quando acontece                                  |
| --------------------------- | ------------------------------------------------ |
| Login                       | O agente entra no painel e fica disponível       |
| Logout                      | O agente sai do painel                           |
| Início de pausa             | O agente entra em pausa (ex.: almoço, banheiro)  |
| Fim de pausa                | O agente sai da pausa                            |
| Início de chamada           | O agente entra em uma ligação                    |
| Toque (ringing)             | O telefone do agente está tocando                |
| Fim de chamada / disponível | A ligação terminou e o agente está livre de novo |

> Esses são os eventos de **agente** disponíveis hoje. Outras
> categorias de eventos serão adicionadas no futuro (por exemplo,
> eventos de discagem) — elas vão aparecer 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](https://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](/webhooks/referencia-tecnica)
— lá tem o formato exato do JSON de cada evento, os headers enviados,
e exemplos de código para validar as chamadas.