Webhooks

Webhooks avisam seu servidor quando algo acontece no MailLeader. Você cria um endpoint HTTPS, escolhe os eventos e valida cada requisição com o secret HMAC do webhook.

Configurar

No painel, abra Desenvolvedor > Webhooks > Novo Webhook. Informe um nome, o endpoint e os eventos. Para eventos de toda a conta, deixe o domínio sem seleção. Eventos de campanha, lead e assinatura são sempre da conta e não aceitam filtro por domínio.

O endpoint deve usar HTTPS público na porta 443. URLs com usuário/senha, IP ou host privado e redirecionamentos não são aceitos. Headers adicionais são opcionais; headers x-mailleader-* e headers de transporte são reservados.

Ao criar o webhook, o MailLeader gera um secret de 32 bytes e o mostra uma única vez. Guarde-o em um cofre de segredos no servidor que receberá as chamadas. A chave não pode ser consultada depois. Se ela for perdida, use Gerar novo secret na gestão do webhook; a chave anterior para de validar imediatamente.

Eventos disponíveis

Selecione um ou mais eventos na criação ou edição. Os nomes abaixo são os valores enviados no campo event.

Sites

Evento	O que significa
`page.viewed`	O pixel consentido registrou uma página. Não prova atividade humana.
`link.clicked`	O pixel registrou um clique em link do site. Só a origem do destino é enviada.
`visitor.identified`	O servidor associou uma sessão consentida a um contato por formulário ou token de uso único.
`site.custom`	Evento personalizado habilitado na configuração do site. Pode incluir `properties` JSON aninhado de até 2 KB.

E-mail e campanhas

Evento	O que significa
`smtp.email.accepted`	Uma mensagem de campanha foi aceita para submissão SMTP.
`smtp.email.queued`	Mensagem registrada na fila de saída.
`smtp.email.rejected`	Envio recusado durante a submissão ou por uma política.
`smtp.email.delivered`	O servidor do destinatário aceitou a mensagem; isso não confirma a caixa de entrada.
`smtp.email.deferred`	A entrega foi temporariamente adiada.
`smtp.email.bounced`	O servidor do destinatário recusou a entrega.
`smtp.email.expired`	A mensagem expirou na fila de envio.
`smtp.email.opened`	O pixel de abertura foi solicitado; proxies podem acionar o evento.
`smtp.email.clicked`	Um link de campanha recebeu o primeiro clique classificado como não automatizado. Não comprova interação humana.
`campaign.created`	Uma nova campanha ou rascunho foi criado.
`campaign.queued`	Uma campanha foi publicada ou agendada.
`campaign.started`	O primeiro destinatário começou a ser processado.
`campaign.completed`	O processamento terminou sem falhas confirmadas ou resultados pendentes de confirmação.
`campaign.failed`	O processamento terminou com falhas ou resultados pendentes de confirmação.

Entrega, abertura, clique e conclusão do processamento são acontecimentos diferentes. Os eventos não devem ser tratados como confirmação de compra ou de leitura humana.

Leads e assinaturas

Evento	O que significa
`lead.created`	Um formulário aceitou um cadastro. Inclui os campos do formulário em `lead.data`.
`account.subscription.created`	Uma assinatura foi criada, ativa ou aguardando pagamento.
`account.subscription.activated`	Uma assinatura foi efetivamente ativada.
`account.subscription.change_requested`	Uma troca de plano ou ativação foi solicitada. A solicitação pode ainda não estar aplicada.
`account.subscription.plan_changed`	Uma alteração de plano entrou em vigor.
`account.subscription.change_cancelled`	Um downgrade agendado foi cancelado; a assinatura não foi cancelada.

Domínios e contas de e-mail

Evento	O que significa
`account.domain.created`	Um domínio foi adicionado à conta.
`account.domain.verified`	O domínio passou pelas verificações DNS exigidas para ativação.
`account.domain.status_changed`	O estado do domínio mudou.
`account.domain.deleted`	Um domínio foi removido.
`account.email_account.created`	Uma identidade de envio ou caixa foi criada.
`account.email_account.updated`	A configuração de uma identidade ou caixa foi alterada.
`account.email_account.deleted`	Uma identidade de envio ou caixa foi removida.

Credenciais, tokens, chaves DKIM e dados de pagamento não são enviados nesses eventos.

Formato do corpo

O corpo JSON inclui event, eventId, timestamp e os campos próprios do evento no mesmo nível. Não há um objeto externo data envolvendo o payload.

Exemplo de lead.created:

{
  "event": "lead.created",
  "eventId": "57d3e91b-7c3f-4fc0-9055-5a5a7f19a002",
  "timestamp": "2026-10-15T19:54:02.223Z",
  "leadId": "898660008068124672",
  "campaignId": "898591276704731136",
  "listId": null,
  "consented": false,
  "lead": {
    "id": "898660008068124672",
    "data": {"name":"Ana Silva","email":"ana@example.com"},
    "consentAt": null
  }
}

lead.data contém os campos aceitos pelo formulário. O evento não inclui IP, user-agent nem identificadores de anúncios.

Exemplo de site.custom:

{
  "event": "site.custom",
  "eventId": "b6ae4736-9fd6-4667-a8ee-a4b61fd99031",
  "timestamp": "2026-10-15T19:54:02.223Z",
  "siteId": "468ebe45-2eb5-4568-9412-72e3565c6f4a",
  "path": "/precos",
  "origin": "https://empresa.example",
  "name": "demo.requested",
  "properties": {
    "button": "hero",
    "lead": {"source":"ebook","score":12},
    "products": ["analytics","automation"]
  },
  "contactId": null,
  "sessionId": "7d21cda4-6dbc-4e36-8e3b-4e420bcc6158",
  "classification": "unclassified"
}

As propriedades personalizadas são definidas no site que envia o evento e aceitam JSON aninhado de até 2 KB. Não inclua segredos ou informações que não devam ser armazenadas e encaminhadas ao seu endpoint.

Como o HMAC funciona

O secret é compartilhado entre o MailLeader e seu endpoint. O MailLeader calcula HMAC-SHA256 sobre o timestamp, um ponto e os bytes originais do corpo HTTP:

HMAC_SHA256(secret, timestamp + "." + rawBody)

Cada requisição inclui:

Header	Conteúdo
`x-mailleader-timestamp`	Timestamp Unix em segundos.
`x-mailleader-signature`	`sha256=` seguido do HMAC hexadecimal.
`x-mailleader-event-id`	ID usado para deduplicar eventos e tentativas repetidas.

O endpoint deve validar a assinatura antes de confiar no JSON. Leia o corpo bruto antes de decodificá-lo: reserializar o objeto JSON pode mudar os bytes e invalidar a assinatura. Compare a assinatura em tempo constante e rejeite timestamps antigos (por exemplo, com mais de cinco minutos).

Exemplo de receptor em Node.js

Este exemplo usa express.raw() para validar os mesmos bytes que foram assinados. Configure MAILLEADER_WEBHOOK_SECRET no ambiente do servidor.

Em produção, registre o eventId em uma tabela com índice único e só responda 2xx depois de aceitar o evento com segurança. Se o mesmo ID já tiver sido processado, responda 2xx sem repetir a operação.

Retentativas e histórico

O MailLeader considera sucesso uma resposta HTTP 2xx. Falhas de rede e outras respostas recebem novas tentativas automáticas com espera exponencial; são feitas até 10 tentativas, começando em 30 segundos. Redirecionamentos não são seguidos.

Na gestão do webhook, consulte o histórico para ver estado, horário, código HTTP e erro sanitizado. O payload e o secret não aparecem no histórico. Uma entrega que falhou pode ser reenviada manualmente; o eventId original é mantido, então o endpoint deve deduplicar.

Rotas de gestão

Método e rota	Uso
`GET /api/v1/webhook/events`	Consultar catálogo de eventos.
`POST /api/v1/webhook`	Criar webhook; o retorno contém o secret, exibido uma única vez.
`GET /api/v1/webhook`	Listar webhooks sem revelar secrets ou headers.
`GET /api/v1/webhook/{id}`	Consultar um webhook sem revelar o secret.
`PATCH /api/v1/webhook/{id}`	Editar nome, URL, eventos, domínio ou headers.
`PATCH /api/v1/webhook/{id}/status`	Ativar ou pausar entregas futuras.
`POST /api/v1/webhook/{id}/secret/rotate`	Gerar secret novo; invalida o anterior.
`POST /api/v1/webhook/{id}/test`	Enfileirar um evento de teste `webhook.test`.
`GET /api/v1/webhook/{id}/deliveries`	Consultar entregas e tentativas.
`POST /api/v1/webhook/{id}/deliveries/{deliveryId}/retry`	Solicitar reenvio de uma entrega falha.
`DELETE /api/v1/webhook/{id}`	Excluir webhook.

Essas rotas de gestão exigem autenticação. O endpoint que recebe as notificações é o seu serviço e valida o HMAC usando o secret guardado no momento da criação ou rotação.

Configurar#

Eventos disponíveis#

Sites#

E-mail e campanhas#

Leads e assinaturas#

Domínios e contas de e-mail#

Formato do corpo#

Como o HMAC funciona#

Exemplo de receptor em Node.js#

Retentativas e histórico#

Rotas de gestão#