Webhooks
Este guia acompanha a tela Webhooks do painel (Integrações → Webhooks).
Para que serve
Avisar o seu sistema (CRM, loja, ERP) quando algo importante acontece na sua conta — por exemplo um contato novo ou um e-mail avulso enviado pela API — sem ficar consultando a API o tempo todo.
O que você vai fazer
- Abrir Integrações → Webhooks.
- Clicar em Novo webhook e informar a URL HTTPS do seu sistema.
- Marcar os eventos que quer receber.
- Copiar o secret imediatamente após criar — por segurança ele não aparece de novo.
- No seu sistema, validar o cabeçalho de assinatura com esse secret.
- Usar Testar para enviar um aviso de prova.
Eventos comuns
| Evento | Quando |
|---|---|
| Contato criado / atualizado | Painel, formulário ou API de contatos |
| Mensagem enviada / falhou | Envio avulso pela API (/messages) |
| Campanha concluída | Quando um disparo de campanha termina |
Secret e segurança
O secret serve para o seu sistema confirmar que o aviso veio mesmo do Br Envio. Guarde-o como senha. Se vazar, use Gerar novo secret na edição do webhook.
Detalhes técnicos (HMAC, cabeçalhos e exemplos de código): portal da API.
Dica
Mantenha a URL sempre em https://. Se pausar o webhook, param os avisos até reativar.
Na edição do webhook você vê as entregas recentes (se chegou, qual status HTTP e se houve erro) — útil para conferir se o seu sistema respondeu.
Há um limite de webhooks por conta (padrão: 10). Se precisar de mais, fale com o suporte.
Relação com envios avulsos (API)
Os eventos de mensagem enviada / falhou acompanham o POST /messages do portal da API. Se a API recusar um envio por capacidade do momento (muitos avulsos ao mesmo tempo), a mensagem na resposta explica em português — espere um pouco e tente de novo; isso não é o mesmo que “acabou a cota do plano”.
Marketing precisa de link para sair da lista
Se message_type for marketing, o HTML deve trazer um link de cancelamento. O jeito mais simples:
<a href="{{brenvio_track_unsub}}">Cancelar inscrição</a>No envio, a plataforma troca o placeholder pela URL real. Sem isso a API responde erro MARKETING_UNSUB_REQUIRED (mensagem amigável). Detalhes e exemplos: portal da API — Envio avulso.