Webhooks
Configure webhooks para receber eventos em tempo real quando mensagens são recebidas, enviadas ou quando o status da instância muda.
Configuração
Acesse as configurações da instância
No dashboard, vá em Instância → Configurações → Webhook.
Insira a URL do webhook
Informe a URL do seu servidor que receberá os eventos HTTP POST.
Ative os eventos desejados
Selecione quais eventos devem ser enviados para seu webhook.
Segurança
Implemente estas proteções no seu servidor:
- Validação HMAC: Valide a assinatura com o segredo configurado
- Validação de timestamp: Rejeite requisições antigas (> 5 minutos)
- Idempotência: Evite processar o mesmo evento duas vezes
- Não exponha credenciais: Nunca inclua chaves API no frontend
Eventos Disponíveis
| Evento | Descrição |
|---|
| Mensagem recebida | Nova mensagem do cliente |
| Mensagem enviada | Confirmação de envio |
| Status da instância | Conexão/desconexão |
Payload Exemplo
{
"event": "message_received",
"instanceId": "SUA_INSTANCIA",
"phone": "5511999999999",
"message": {
"type": "text",
"content": "Olá, preciso de ajuda",
"timestamp": "2024-01-15T10:30:00Z"
},
"contact": {
"name": "João Silva",
"phone": "5511999999999"
}
}
Retry Policy
Se seu servidor retornar erro (status ≥ 400) ou timeout (> 10s), o Brainchat tentará reenviar:
- 1ª tentativa: imediata
- 2ª tentativa: após 30 segundos
- 3ª tentativa: após 2 minutos
Após 3 falhas, o evento é descartado.
Sempre retorne status 200 o mais rápido possível. Processe a lógica de negócio de forma assíncrona para evitar timeouts.
