Receber eventos ao vivo com webhooks

Até agora, nas integrações por API, seu sistema falava com a arrobaMail: você pedia o token, cadastrava um contato, enviava. Os webhooks de eventos invertem essa direção: agora a arrobaMail fala com seu sistema. Toda vez que algo acontece — uma campanha terminou de ser enviada, alguém abriu, um e-mail rejeitou, alguém se descadastrou —, a arrobaMail manda um aviso para um servidor seu, na hora.

É a peça que permite ter seus próprios dados sempre atualizados: auditar, sincronizar sua base, ou disparar sua lógica de negócio em resposta ao que sua audiência faz. Veja o sentido do fluxo:

1. O que são os webhooks de eventos

Um webhook é, de forma simples, uma chamada que um sistema faz a outro quando algo acontece. Neste caso, você configura uma URL do seu servidor na arrobaMail e, a partir daí, ela faz um POST HTTP para essa URL cada vez que ocorre um evento, com os dados do que aconteceu. Você não precisa ficar perguntando "abriu? abriu?": a arrobaMail avisa sozinha.

Cuidado para não confundir com o nó Webhook de uma automação. Aquele (que vimos em transacionais) dispara um POST quando um contato passa por um ponto de um fluxo. Os webhooks de eventos deste guia são diferentes: eles notificam sobre os eventos de e-mail (aberturas, rejeições…) à medida que ocorrem.

2. Para que servem

Receber os eventos ao vivo permite:

• Auditar e reportar com seus próprios painéis, sem entrar na plataforma.
• Sincronizar seu banco de dados: marcar no seu CRM quem abriu, quem rejeitou, quem se descadastrou — e manter seu status atualizado.
• Acionar: disparar lógica de negócio quando algo acontece (por exemplo, se um cliente importante clica na sua oferta, avisar a equipe de vendas).

3. Configure sua URL

Na configuração da sua conta, cole a URL pública do seu servidor que vai receber os avisos. Precisa ser HTTPS (não são aceitas URLs sem criptografia). Algo como:

https://seu-servidor.com/webhooks/arrobamail

Essa URL é a "caixa de correio" onde a arrobaMail vai deixar cada evento.

4. Os eventos que você vai receber

A arrobaMail notifica sobre os eventos do ciclo de vida dos seus envios. Os principais:

• campaign.sent — uma campanha terminou seu envio.
• contact.open — um contato abriu um e-mail.
• contact.click — um contato clicou em um link.
• contact.bounce — um e-mail rejeitou (bounce), com seu tipo: temporário ou permanente.
• contact.complaint — alguém marcou seu e-mail como spam.
• contact.unsubscribe — alguém se descadastrou.
• automation.triggered — um contato entrou num fluxo de automação.

Cada POST traz os dados do evento (o contato, a campanha, o momento). A estrutura exata do payload vale a pena confirmar nos seus primeiros testes (vemos isso no passo 6).

5. Programe o receptor

Seu servidor precisa escutar esse POST, ler o JSON, executar sua lógica e responder HTTP 200 para que a arrobaMail saiba que você recebeu. Um receptor mínimo em PHP:

<?php // webhooks/arrobamail
$payload = json_decode(file_get_contents("php://input"), true);

$event = $payload["event"]   ?? null;   // ex: contact.bounce
$email = $payload["email"]   ?? null;

switch ($event) {
    case "contact.bounce":
        // marque o e-mail como rejeitado (bounce) na sua base
        break;
    case "contact.unsubscribe":
        // dê baixa dele também no seu CRM
        break;
    // ...outros eventos que te interessem
}

http_response_code(200);
echo json_encode(["status" => "ok"]);

A ideia é sempre a mesma em qualquer linguagem: ler o body, olhar o tipo de evento, fazer o seu, responder 200.

6. Teste e depure

Antes de confiar na sua lógica, veja o que chega de verdade:

• Registre o payload completo nos primeiros testes. Assim você vê exatamente quais campos a arrobaMail manda para cada evento, em vez de adivinhar.
• Use o histórico de eventos da sua conta (em Ferramentas) para ver o registro do que foi enviado e cruzar com o que seu servidor recebeu. É a principal ferramenta para depurar a integração.

7. Boas práticas

• Responda rápido. Seu receptor deve responder 200 imediatamente. Se tiver trabalho pesado, coloque numa fila e processe à parte; não deixe o webhook esperando.
• Deixe-o idempotente. O mesmo evento pode chegar mais de uma vez. Desenhe sua lógica para que receber "rejeitou" duas vezes não quebre nada (por exemplo, marcando por ID do evento).
• Verifique a origem. Aceite apenas o que chegar na sua URL secreta (e, se quiser mais segurança, valide o conteúdo antes de agir).
• Não dependa só do webhook para dados críticos. Para relatórios exatos, complemente com consultas à API (os webhooks são para reagir ao vivo; a API, para a verdade consolidada).

Erros comuns para evitar

• URL sem HTTPS. Não é aceita. Seu endpoint precisa ser criptografado.
• Não responder 200. Se seu servidor não confirmar, a arrobaMail pode considerar o envio como falho.
• Assumir o formato do payload. Registre primeiro, programe depois. Os campos você confirma vendo o que chega.
• Processar coisa pesada dentro do webhook. Coloque o trabalho numa fila e responda rápido, ou você vai ter timeouts.

Próximos passos

1. Revise o panorama de todas as formas de integrar em conectar a arrobaMail aos seus sistemas.
2. Combine-os com envios a partir do seu sistema em enviar e-mails transacionais.
3. Veja a API completa em API REST v3 e sua referência.