Webhooks

Os webhooks enviam eventos do Emailit para a sua aplicação à medida que acontecem, para que você não precise consultar a API periodicamente. Use-os para atualizar o status de entrega no seu banco de dados, parar de enviar e-mails para endereços que dão bounce ou reclamam, reagir a aberturas e cliques, processar e-mails recebidos ou sincronizar contatos e supressões.

Como funciona

1. Você registra um endpoint. Crie um webhook com um nome e uma URL HTTPS no painel ou pela API. O Emailit gera um segredo de assinatura para ele.
2. Algo acontece. O Emailit registra um evento, por exemplo email.delivered, e o coloca na fila de cada webhook ativado que esteja inscrito nesse tipo de evento e cujo filtro de payload corresponda a ele.
3. O Emailit envia um lote. Em poucos segundos, o Emailit envia uma requisição POST cujo corpo é um array JSON de até 100 eventos da fila, do mais antigo para o mais recente. As requisições para um mesmo webhook são enviadas uma de cada vez.
4. O seu endpoint responde. Qualquer status 2xx em até 30 segundos marca todos os eventos do lote como entregues. Qualquer outra resposta, incluindo um timeout ou um redirecionamento, é uma falha, e o lote recebe novas tentativas por cerca de três dias.

Cada requisição tem estes cabeçalhos:

Consulte Requisições de webhook para ver o formato completo e Assinatura da requisição para ver o código de verificação.

Exemplo rápido

Este handler do Express verifica a assinatura e depois processa cada evento do lote:

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/emailit', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-Emailit-Timestamp') ?? '';
  const signature = req.get('X-Emailit-Signature') ?? '';
  const expected = crypto
    .createHmac('sha256', process.env.EMAILIT_WEBHOOK_SECRET) // whsec_...
    .update(`${timestamp}.`)
    .update(req.body)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  const valid = a.length === b.length && crypto.timingSafeEqual(a, b);
  if (!fresh || !valid) return res.status(401).send('Invalid signature');

  for (const event of JSON.parse(req.body)) {
    switch (event.type) {
      case 'email.delivered':
        console.log(`Delivered ${event.data.object.id} to ${event.data.object.to}`);
        break;
      case 'email.bounced':
      case 'email.complained':
        console.log(`Stop sending to ${event.data.object.to}`);
        break;
    }
  }

  res.sendStatus(200);
});

app.listen(3000);

Eventos disponíveis para inscrição

Os webhooks cobrem a entrega e o engajamento de e-mails (email.delivered, email.bounced, email.clicked e mais), o recebimento de e-mails (email.received) e as mudanças em domínios, listas de contatos, inscritos, contatos, templates, supressões, verificações de e-mail e campanhas. Um webhook novo criado no painel recebe todos os eventos; depois, você pode restringi-lo a tipos específicos. Consulte Tipos de evento.

Nos planos Pro, Business e Custom, um filtro de payload pode limitar um webhook aos eventos que correspondem a regras, por exemplo apenas e-mails para um domínio.

Limites

A página de webhooks mostra quantos endpoints você está usando, por exemplo 2/3 used. Quando você atinge o limite, o botão Add webhook fica desativado até você excluir um endpoint ou fazer upgrade. Cada webhook pode enviar no máximo 5 eventos de teste por minuto.

Primeiros passos