Webhooks

Visão geral

Os webhooks permitem que você receba requisições HTTP POST no seu servidor quando eventos acontecem no Madmail, como quando um e-mail é entregue, sofre bounce ou é clicado. Com isso você constrói integrações em tempo real e automatiza fluxos de trabalho.

Configurando webhooks

1. Crie um endpoint de webhook

   Crie um endpoint no seu servidor capaz de receber requisições POST. O endpoint precisa:

   • Aceitar requisições POST com corpo JSON
   • Retornar um status 2xx para confirmar o recebimento
   • Responder em até 10 segundos
2. Adicione o webhook no dashboard

   Acesse Webhooks no seu dashboard do Madmail e crie um novo webhook:

   • Informe a URL do seu endpoint
   • Selecione quais eventos você quer receber
   • Copie o secret de assinatura para a verificação
3. Verifique as assinaturas dos webhooks

   Sempre verifique as assinaturas para garantir que as requisições vêm do Madmail. Veja a seção Verificação de assinatura abaixo.

Tipos de evento

Eventos de e-mail

Eventos de contato

Eventos de domínio

Payload do webhook

Cada requisição de webhook inclui um payload JSON com a estrutura abaixo. Veja Detalhes dos dados de evento para saber o conteúdo do campo data em cada tipo de evento.

{
  "id": "call_abc123",
  "type": "email.delivered",
  "version": "2026-01-18",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "teamId": 123,
  "data": {
    "id": "email_123",
    "status": "DELIVERED",
    "from": "sender@example.com",
    "to": ["recipient@example.com"],
    "subject": "Welcome!",
    "occurredAt": "2024-01-15T10:30:00Z"
  },
  "attempt": 1
}

Campos do payload

Cabeçalhos da requisição

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

Verificação de assinatura

Sempre verifique as assinaturas dos webhooks para garantir que as requisições são autênticas. A assinatura é calculada assim:

HMAC-SHA256(secret, "${timestamp}.${rawBody}")

Usando o SDK (recomendado)

npm install usesend-js

yarn add usesend-js

pnpm add usesend-js

bun add usesend-js

Next.js App Router

import { UseSend } from "usesend-js";

const usesend = new UseSend("us_your_api_key");
const webhooks = usesend.webhooks(process.env.USESEND_WEBHOOK_SECRET!);

export async function POST(request: Request) {
  try {
    const rawBody = await request.text();
    const event = webhooks.constructEvent(rawBody, {
      headers: request.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
      case "email.opened":
        console.log("Email opened:", event.data.id);
        break;
    }

    return new Response("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    return new Response((error as Error).message, { status: 400 });
  }
}

Express

import express from "express";
import { Webhooks } from "usesend-js";

const webhooks = new Webhooks(process.env.USESEND_WEBHOOK_SECRET!);

const app = express();

// Important: Use raw body parser for webhook routes
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = webhooks.constructEvent(req.body, {
      headers: req.headers,
    });

    switch (event.type) {
      case "email.delivered":
        console.log("Email delivered to:", event.data.to);
        break;
      case "email.bounced":
        console.log("Email bounced:", event.data.id);
        break;
    }

    res.status(200).send("ok");
  } catch (error) {
    console.error("Webhook error:", error);
    res.status(400).send((error as Error).message);
  }
});

app.listen(3000);

Apenas verificação

Se você só precisa verificar a assinatura, sem fazer o parse do evento:

const isValid = webhooks.verify(rawBody, { headers: request.headers });

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

Verificação manual

Se você preferir verificar manualmente, sem o SDK:

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(
  secret: string,
  rawBody: string,
  signature: string,
  timestamp: string,
): boolean {
  const expectedSignature = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const expected = Buffer.from(`v1=${expectedSignature}`, "utf8");
  const received = Buffer.from(signature, "utf8");

  if (expected.length !== received.length) {
    return false;
  }

  return timingSafeEqual(expected, received);
}

// Usage
const signature = request.headers.get("X-UseSend-Signature");
const timestamp = request.headers.get("X-UseSend-Timestamp");

const isValid = verifyWebhook(secret, rawBody, signature, timestamp);

Comportamento de retentativa

Se o seu endpoint não retornar uma resposta 2xx, o Madmail vai tentar entregar novamente com backoff exponencial:

Depois de 6 tentativas sem sucesso, a chamada do webhook é marcada como falha.

Boas práticas

Testando webhooks

Você pode enviar um webhook de teste pelo dashboard para verificar se o seu endpoint está funcionando corretamente:

1. Acesse Webhooks
2. Clique no seu webhook
3. Clique em “Send Test” para enviar um evento de teste

O evento de teste terá o tipo webhook.test com o seguinte payload:

{
  "test": true,
  "webhookId": "wh_abc123",
  "sentAt": "2024-01-15T10:30:00.000Z"
}

Solução de problemas

Detalhes dos dados de evento

Esta seção documenta a estrutura do campo data para cada tipo de evento.

Eventos de e-mail

A maioria dos eventos de e-mail compartilha uma estrutura base comum:

{
  id: string;              // Email ID
  status: string;          // Email status (e.g., "DELIVERED", "BOUNCED")
  from: string;            // Sender email address
  to: string[];            // Recipient email addresses
  occurredAt: string;      // ISO 8601 timestamp
  subject?: string;        // Email subject
  campaignId?: string;     // Campaign ID (if from a campaign)
  contactId?: string;      // Contact ID (if sent to a contact)
  domainId?: number;       // Domain ID
  templateId?: string;     // Template ID (if using a template)
  metadata?: object;       // Custom metadata you attached to the email
}

email.bounced

Inclui detalhes adicionais do bounce:

{
  // ... base email fields
  bounce: {
    type: "Transient" | "Permanent" | "Undetermined";
    subType: "General" | "NoEmail" | "Suppressed" | "OnAccountSuppressionList"
           | "MailboxFull" | "MessageTooLarge" | "ContentRejected" | "AttachmentRejected";
    message?: string;      // Bounce message from the mail server
  }
}

email.failed

Inclui o motivo da falha:

{
  // ... base email fields
  failed: {
    reason: string; // Failure reason
  }
}

email.suppressed

Inclui detalhes da supressão:

{
  // ... base email fields
  suppression: {
    type: "Bounce" | "Complaint" | "Manual";
    reason: string;        // Why the email was suppressed
    source?: string;       // Source of the suppression
  }
}

email.opened

Inclui detalhes do rastreamento de abertura:

{
  // ... base email fields
  open: {
    timestamp: string;     // When the email was opened
    userAgent?: string;    // Browser/client user agent
    ip?: string;           // IP address
    platform?: string;     // Detected platform
  }
}

email.clicked

Inclui detalhes do rastreamento de cliques:

{
  // ... base email fields
  click: {
    timestamp: string;     // When the link was clicked
    url: string;           // The clicked URL
    userAgent?: string;    // Browser/client user agent
    ip?: string;           // IP address
    platform?: string;     // Detected platform
  }
}

Eventos de contato

Todos os eventos de contato (contact.created, contact.updated, contact.deleted) incluem:

{
  id: string;              // Contact ID
  email: string;           // Contact email address
  contactBookId: string;   // Contact book ID
  subscribed: boolean;     // Subscription status
  properties: object;      // Custom properties
  firstName?: string;      // First name
  lastName?: string;       // Last name
  createdAt: string;       // ISO 8601 timestamp
  updatedAt: string;       // ISO 8601 timestamp
}

Eventos de domínio

Todos os eventos de domínio (domain.created, domain.verified, domain.updated, domain.deleted) incluem:

{
  id: number;              // Domain ID
  name: string;            // Domain name (e.g., "example.com")
  status: string;          // Domain status
  region: string;          // AWS region
  createdAt: string;       // ISO 8601 timestamp
  updatedAt: string;       // ISO 8601 timestamp
  clickTracking: boolean;  // Click tracking enabled
  openTracking: boolean;   // Open tracking enabled
  subdomain?: string;      // Subdomain for tracking
  dkimStatus?: string;     // DKIM verification status
  spfDetails?: string;     // SPF record details
  dmarcAdded?: boolean;    // DMARC record added
}