Requisições de Webhook

Quando um evento ocorre, o Emailit envia uma requisição HTTP POST para a URL do webhook que você configurou. Esta página descreve o formato da requisição, cabeçalhos e comportamento de entrega.

Formato da requisição

Todas as requisições de webhook são enviadas como requisições POST com corpo JSON:

• Método: POST
• Content-Type: application/json
• Timeout: 30 segundos

Cabeçalhos

Cada requisição de webhook inclui os seguintes cabeçalhos:

Corpo da requisição

O corpo da requisição contém os dados do evento em formato JSON:

{
  "event_id": "evt_2bH7kNwP5mQaV1sXgIdKe6pZr",
  "type": "email.delivered",
  "data": {
    "object": {
      "id": "em_4yM2nTvR8oPcX3uZiKeLg7sB",
      "object": "email",
      ...
    }
  }
}

Resposta esperada

Seu endpoint deve retornar um código de status 2xx (ex.: 200, 201, 204) para confirmar o recebimento. Qualquer outro código de status é tratado como falha.

Política de reenvio

Se seu endpoint não responder com um código de status 2xx dentro de 30 segundos, o Emailit tentará reenviar a entrega seguindo o cronograma abaixo:

Após a tentativa 6 (7 tentativas no total), o webhook é automaticamente desabilitado. Você pode reativá-lo através do painel do Emailit.

Ordenação

Os eventos de webhook são entregues quase em tempo real, mas não há garantia de que cheguem em ordem. Use o event_id e os timestamps dentro dos dados do evento para gerenciar a ordenação em sua aplicação.

Endereços IP

As requisições de webhook são enviadas a partir da infraestrutura do Emailit. Se você precisar incluir IPs em uma lista de permissões, entre em contato com o suporte para obter a lista atual de endereços IP de saída.

Boas práticas

• Responda rapidamente — Processe o webhook de forma assíncrona e retorne um 2xx imediatamente. Faça processamentos pesados em tarefas em segundo plano.
• Trate duplicatas — Use o event_id para eliminar eventos duplicados. O mesmo evento pode ser entregue mais de uma vez durante os reenvios.
• Verifique assinaturas — Sempre valide o cabeçalho X-Emailit-Signature para garantir que a requisição veio do Emailit. Consulte Assinatura de Requisição.