Webhooks: receber os eventos de e-mail no seu sistema

5 min de leitura66
Copiar para a I.A.:

O webhook é o caminho de volta da integração: o WiseData Mail avisando o seu sistema do que aconteceu com cada e-mail — entregue, devolvido, aberto, clicado, descadastrado. Com ele, a loja virtual da Casa Moura Cafés sabe que o pedido-confirmado de um cliente voltou devolvido e pode pedir outro e-mail no próximo acesso.

O cadastro é feito só pelo painel, em Configurações › Webhooks, e o histórico fica em Configurações › Eventos webhook. As duas abas são do Dono. Se elas não aparecem para você, fale com o suporte.

Cadastrar um webhook

Clique em Novo webhook e preencha:

  • Endereço — começando com https://, alcançável pela internet, como https://casamoura.com.br/webhooks/mail. Endereço que aponta para dentro de uma rede interna é recusado, e redirecionamento não é seguido: o seu servidor precisa responder no próprio endereço cadastrado.
  • Descrição — qual sistema recebe estes eventos.
  • Eventos assinados — marque ao menos um. Dois têm aviso próprio: Aceito pelo provedor chega um por mensagem enviada (alto volume, só vale se você mede o funil), e os eventos de domínio (Domínio pronto para enviar, Domínio não ficou pronto, Domínio deixou de estar pronto) falam do domínio, não de uma mensagem, e chegam sem e-mail de destinatário — o seu receptor precisa aceitar isso.
  • De onde receber — aparece com espaços de envio na conta. Sem nenhum marcado, o webhook recebe a conta inteira, inclusive espaços criados depois. Marcando espaços, recebe só os deles, sem os da conta principal.
  • Receber eventos — desligado, o webhook fica Pausado.

Um webhook novo começa a receber a partir do momento em que é criado. Eventos de antes do cadastro não são enviados.

O segredo aparece uma vez

Ao salvar, a janela Webhook criado mostra o segredo. Copie na hora: ele não aparece de novo. Cada lote chega assinado, e é com esse segredo que o seu sistema confere a assinatura antes de confiar no conteúdo. Lote com assinatura que não confere deve ser recusado.

Como os eventos chegam

  • Em lote — vários eventos por chamada, não um por vez. Numa campanha grande, isso evita milhares de chamadas ao seu servidor.
  • Responda 2xx, e rápido. Qualquer outra resposta conta como falha, e o lote é reenviado automaticamente. Guarde o lote e processe depois; não faça o WiseData Mail esperar o seu processamento.
  • Prepare-se para receber o mesmo lote duas vezes. Um lote reenviado chega igual ao original; o seu receptor deve ignorar o que já processou.
  • Não é tempo real. Há alguns instantes entre o evento e a entrega — não use o webhook como gatilho de algo que alguém está esperando na tela.

Ativo, pausado e desativado por falhas

  • Ativo — recebendo.
  • Pausado — você desligou Receber eventos. Religue pela edição.
  • Desativado por falhas — depois de uma sequência de lotes falhados, o WiseData Mail desliga o webhook sozinho e o Dono recebe um e-mail. A lista mostra quantos lotes falharam seguidos e a data da última entrega bem-sucedida.

Antes de clicar em Reativar, corrija o seu servidor — senão ele volta a falhar. E saiba que os eventos do período desligado não são reenviados: o histórico mostra o que ficou para trás. Salvar uma edição do webhook também zera a contagem de falhas.

Os botões de cada webhook

  • Testar — bate no seu endereço na hora e mostra o que ele respondeu (código e tempo). O teste não entra no histórico e não conta para o desligamento automático.
  • Histórico — abre Eventos webhook já filtrado neste webhook.
  • Trocar segredo — gera um segredo novo e o atual deixa de valer na hora. Não existe período com os dois válidos: entre a troca e a instalação do novo, o seu servidor vai recusar as entregas. Os lotes que falharem nesse intervalo são reenviados automaticamente, então instale o novo segredo logo.
  • Editar — endereço, descrição, eventos, espaços e o interruptor.
  • Remover — o seu sistema para de receber na hora, e o histórico de entregas é apagado junto. Se você só perdeu o segredo, prefira Trocar segredo: o histórico fica.

O histórico de entregas

Em Eventos webhook, escolha o webhook (se houver mais de um) e veja cada lote: Quando, Situação (Pendente, Entregue ou Falhou), quantos Eventos e quantas Tentativas.

Ver abre o detalhe do lote:

  • Corpo enviado — exatamente o que foi assinado. Quando a assinatura não confere do seu lado, compare com o que o seu servidor recebeu: a diferença costuma estar em o corpo ter sido lido já convertido, e não como chegou.
  • Tentativas — cada uma com o código que o seu servidor respondeu, o tempo e um trecho da resposta. sem resposta quer dizer que o servidor não respondeu a tempo ou nem foi alcançado — o problema está antes do seu código.

Lote que não foi entregue tem o botão Reenviar, na tabela e no detalhe. Use depois de corrigir o seu servidor para recuperar o que falhou.

Para quem integra

Cada evento traz o tipo, o e-mail do destinatário, a mensagem, a campanha (vazia no transacional), o espaço de onde saiu e, quando o envio foi feito pela API, as tags e os metadados que o seu sistema mandou. Eventos simulados na Caixa de teste chegam ao mesmo endereço, marcados como teste — ignore-os no receptor de produção, senão uma devolução simulada vira descadastro de um cliente de verdade.

Para onde ir depois

  • Caixa de teste — simular uma devolução ou um clique e ver o webhook chegar.
  • Chaves de API — o caminho de ida da integração.
  • Espaços de envio — receber eventos só de alguns espaços.

Resumindo: cadastre um endereço https que responda 2xx rápido, marque só os eventos que o seu sistema usa, guarde o segredo para conferir a assinatura de cada lote, trate lotes repetidos, corrija o servidor antes de reativar um webhook desativado por falhas e use o histórico para descobrir o que não chegou.

Este artigo foi útil?