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, comohttps://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.