Webhooks

Receba eventos assim que acontecem, para que seu sistema saiba sempre o que aconteceu com cada mensagem. Verifique cada requisição pela assinatura.

Como os webhooks funcionam

Cadastre um endpoint HTTPS no painel e escolha os eventos que ele deve receber. Quando algo acontece com uma mensagem, o MigoSMTP envia uma requisição POST com corpo JSON ao seu endpoint.

Tipos de evento

Assine apenas os eventos de que seu sistema precisa. Cada evento traz o ID da mensagem, o destinatário e um timestamp, para você associá-lo à mensagem enviada.

Exemplo de payload

Os payloads são JSON enviados em uma requisição POST. Os valores aqui são apenas exemplos.

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

Verifique a assinatura

Qualquer pessoa que conheça sua URL poderia enviar requisições a ela, então verifique todas. Calcule um HMAC do corpo bruto da requisição com seu segredo de assinatura e compare-o com o valor do cabeçalho de assinatura usando uma comparação em tempo constante. Rejeite as requisições que não coincidirem. O nome do cabeçalho e o algoritmo aparecem no painel junto ao seu segredo de assinatura.

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Responda rápido

Retorne um status 2xx assim que armazenar o evento e faça o trabalho de fato depois, em uma fila. Um endpoint lento ou com falhas gera novas tentativas e pode atrasar seus outros eventos.

Espere duplicatas e eventos fora de ordem

Entregas com falha são repetidas, então o mesmo evento pode chegar mais de uma vez, e os eventos podem chegar fora de ordem. Use o ID da mensagem e o tipo do evento para tornar seu handler idempotente, e use o timestamp do evento em vez do horário de chegada.

Teste antes de depender dele

Aponte o endpoint para um inspetor de requisições ou um túnel até sua máquina de desenvolvimento, envie uma mensagem de teste e confirme que consegue verificar a assinatura em tráfego real.