Webhooks

Um webhook faz o AzChat chamar o seu servidor quando algo acontece. É a alternativa a ficar consultando a API — mais rápido para você e mais leve para a instância.

Criando

Pela interface, em Configurações → Developer → Webhooks, ou pela API:

curl --request POST \
  --url 'https://app.azchat.digital/api/v1/accounts/1/webhooks' \
  --header 'api_access_token: SUA_CHAVE_AQUI' \
  --header 'content-type: application/json' \
  --data '{
    "url": "https://seu-servidor.com/azchat",
    "subscriptions": ["message_created", "conversation_created"]
  }'

A url precisa ser http ou https, e é única por conta: não dá para cadastrar o mesmo endereço duas vezes.

Eventos disponíveis

subscriptions aceita apenas os valores abaixo — qualquer outro faz a requisição falhar com 422.

Evento	Quando dispara
conversation_created	Uma conversa é aberta
conversation_updated	Algum atributo da conversa muda
conversation_status_changed	A conversa muda de status (aberta, resolvida, pendente…)
conversation_typing_on	Alguém começou a digitar
conversation_typing_off	Alguém parou de digitar
message_created	Uma mensagem é criada — de entrada ou de saída
message_updated	Uma mensagem é alterada
contact_created	Um contato é criado
contact_updated	Um contato é alterado
inbox_created	Uma caixa de entrada é criada
inbox_updated	Uma caixa de entrada é alterada
webwidget_triggered	Um visitante abre o widget de chat

Escopo: conta ou caixa de entrada

Um webhook pode valer para a conta inteira (account_type, o padrão) ou para uma caixa específica (inbox_type). Use o escopo por caixa quando a integração só interessa a um canal — evita processar eventos que você vai jogar fora.

Recebendo

O AzChat faz um POST com o payload em JSON. O corpo traz o evento e o recurso envolvido:

{
  "event": "message_created",
  "id": "12345",
  "content": "Olá, preciso de ajuda",
  "message_type": "incoming",
  "conversation": { "id": 42, "status": "open" },
  "sender": { "id": 7, "name": "Maria" }
}

O formato exato varia por evento. Sempre leia event antes de interpretar o resto, e ignore eventos que você não assinou explicitamente — assinaturas podem mudar sem que seu código mude.

Boas práticas

• Responda rápido. Devolva 200 assim que receber e processe em background. O AzChat espera no máximo alguns segundos (WEBHOOK_TIMEOUT, 5s por padrão) antes de considerar a entrega falha.
• Seja idempotente. Uma entrega pode se repetir. Use o id do recurso para não processar duas vezes.
• Tolere campos novos. Não quebre ao encontrar um atributo que você não conhece.
• Valide a origem. O endpoint fica exposto na internet: use uma URL com um segredo difícil de adivinhar e verifique se o payload faz sentido antes de agir.

Testando

Não existe um botão de "reenviar evento". Para desenvolver, aponte o webhook para um túnel local (ngrok, Cloudflare Tunnel) e provoque o evento de verdade — mandando uma mensagem na caixa, por exemplo.