Webhooks transacionais

Os webhooks permitem que a aplicação receba notificações em tempo real quando algo acontece a um e-mail transacional após o envio. Em vez de consultar a API para verificar o estado de entrega, o Flexmail envia um pedido HTTP POST para o endpoint no momento em que ocorre um evento.

Isto é particularmente valioso para e-mail transacional: pode agir imediatamente quando um pedido de redefinição de palavra-passe sofre um bounce, quando uma confirmação de encomenda é entregue, ou quando um destinatário marca uma mensagem como spam.

Eventos de webhook

O Flexmail envia uma notificação de webhook para cada um dos seguintes eventos:

  • Enviado — a mensagem foi aceite e entregue ao servidor de e-mail recetor.
  • Entregue — o servidor de e-mail recetor confirmou a entrega na caixa de entrada do destinatário.
  • Bounce — a entrega falhou. Os hard bounces indicam um problema permanente (o endereço não existe); os soft bounces indicam um problema temporário (caixa de entrada cheia, servidor indisponível).
  • Aberto — o destinatário abriu a mensagem.
  • Clicado — o destinatário clicou numa ligação rastreada na mensagem.
  • Queixa — o destinatário marcou a mensagem como spam.

Nota

O rastreamento de aberturas e cliques requer que os píxeis de rastreamento e o envolvimento de ligações estejam ativados. Os eventos de entrega dependem de o servidor de e-mail recetor confirmar a entrega — nem todos os servidores o fazem.

Configurar um endpoint de webhook

O endpoint de webhook é um URL no servidor que aceita pedidos HTTP POST e devolve uma resposta 200 para confirmar a receção.

Requisitos para o endpoint

  • Aceita pedidos HTTP POST.
  • Está acessível publicamente via HTTPS.
  • Devolve um código de estado HTTP 2xx dentro de um tempo limite razoável para confirmar a receção.
  • Processa o payload de forma assíncrona se a lógica de tratamento for lenta — responda imediatamente e processe em segundo plano para evitar exceder o tempo limite.

Registar o endpoint no Flexmail

A configuração do endpoint de webhook é feita através da API. O processo de registo completo e as opções disponíveis estão documentados na documentação da API em email-api.flexmail.eu/documentation, na secção Webhooks.

Payload do webhook

Cada notificação de webhook é um pedido HTTP POST com um corpo JSON. O payload contém o tipo de evento, um timestamp, o ID da mensagem e o endereço de e-mail do destinatário. Consoante o evento, são incluídos campos adicionais — por exemplo, um evento de bounce inclui o tipo e a razão do bounce, e um evento de clique inclui o URL que foi clicado.

Um payload típico tem este aspeto:

{ "event": "delivered", "timestamp": "2024-11-15T09:32:00Z", "messageId": "abc123", "recipient": "customer@example.com" }

A especificação completa do payload para cada tipo de evento está na documentação da API.

O que fazer com os eventos de webhook

Bounces

Quando receber um evento de hard bounce, sinalize esse endereço de e-mail no sistema. Pare de enviar para ele e investigue se o endereço foi introduzido corretamente. Continuar a enviar para endereços com hard bounce danifica a reputação do remetente.

Queixas de spam

Quando um destinatário marca um e-mail transacional como spam, suprima esse endereço imediatamente. Mesmo que o e-mail fosse genuinamente transacional (uma confirmação de encomenda, por exemplo), o destinatário sinalizou que não quer receber e-mails. Continuar a enviar é prejudicial para a reputação e pode representar um problema legal.

Confirmações de entrega

Para mensagens urgentes como redefinições de palavra-passe ou códigos de autenticação de dois fatores, pode usar o evento de entrega para confirmar que o e-mail chegou à caixa de entrada. Se não chegar nenhuma confirmação de entrega dentro de um período razoável, pode mostrar uma mensagem na interface sugerindo ao utilizador que verifique a pasta de spam ou tente novamente.

Dica

Confirme os pedidos de webhook imediatamente com uma resposta 200 e processe o payload numa tarefa ou fila em segundo plano. Se o handler demorar demasiado a responder, o Flexmail pode exceder o tempo limite e retentar o pedido, o que pode levar a processamento duplicado.

Tentativas repetidas

Se o endpoint não devolver uma resposta de sucesso, o Flexmail retenta a notificação de webhook. Torne o tratamento de eventos idempotente — processar o mesmo evento duas vezes deve produzir o mesmo resultado que processá-lo uma vez. Use o ID da mensagem e o tipo de evento em conjunto para desduplicar.

Próximos passos

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.