Configurar um webhook

Este guia cria um webhook, restringe-o aos eventos de que você precisa e confirma que o seu endpoint recebe requisições assinadas. Você pode fazer tudo no painel ou com a API de webhooks.

Antes de começar

• Uma URL pública que aceite requisições POST. Recomendamos fortemente usar HTTPS. URLs em localhost ou em faixas de IP privadas são rejeitadas; para desenvolvimento local, use um túnel, como ngrok ou Cloudflare Tunnel.
• Um endpoint que preserve o corpo bruto da requisição para poder verificar a assinatura.
• Para a API, uma chave com Full Access.
• Uma vaga de webhook livre. O Pay as you go inclui 3 endpoints, o Pro 10, e o Business e o Custom 100.

Criar o webhook

curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'

Escolher os eventos

Um webhook recebe todos os tipos de evento ou apenas os tipos que você selecionar.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'

Filtrar eventos por payload

Um filtro de payload entrega um evento apenas quando os dados dele correspondem às suas regras. Os filtros se somam à seleção de eventos: um evento precisa estar na seleção e corresponder ao filtro.

Use-o para dividir o tráfego entre endpoints, por exemplo um webhook por linha de produto, ou para descartar eventos que você ignoraria no código de qualquer forma.

• Modo de correspondência: All rules match (all) ou Any rule matches (any).
• Regras: até 25. Cada regra tem um campo, um operador e um valor.
• Campo: um caminho com pontos dentro do data.object do evento, por exemplo to, status, meta.plan ou, para eventos de clique, link.url. O prefixo payload. é opcional, então payload.from e from são equivalentes.
• As comparações diferenciam maiúsculas de minúsculas e comparam os valores como texto, exceto greater_than e less_than, que comparam números.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'

Mais exemplos:

Se um workspace passar para o Pay as you go, os filtros existentes continuam salvos, mas são ignorados, e todos os eventos inscritos são entregues.

Enviar um evento de teste

Um teste envia imediatamente um evento de exemplo para a sua URL, assinado com o segredo atual do webhook. Os eventos inscritos e os filtros são ignorados, a requisição não recebe novas tentativas e não aparece na aba Requests. Cada webhook permite 5 testes por minuto.

curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'

Os eventos de teste usam dados de exemplo, com um event_id que começa com evt_test_, e o formato deles pode diferir um pouco do formato dos eventos reais. Construa o seu handler com base na referência de eventos e confirme com um envio real.

Ativar ou desativar um webhook

Desative um webhook para interromper as entregas sem perder as configurações dele, por exemplo durante uma manutenção.

• Painel: abra o menu de ações e selecione Disable webhook ou Enable webhook. A página do webhook mostra o status Enabled ou Disabled.
• API: chame Atualizar um webhook com {"enabled": false} ou {"enabled": true}.

Enquanto um webhook está desativado, novos eventos não entram na fila dele, e as requisições que já aguardavam uma nova tentativa ficam pausadas. Os eventos que acontecem enquanto ele está desativado não são entregues depois; se precisar deles, leia-os com a API de eventos. O Emailit também desativa webhooks automaticamente após 3 dias de falhas; consulte Novas tentativas e falhas.

Excluir um webhook descarta todos os eventos pendentes dele.

Fazer a rotação do segredo

Faça a rotação do segredo se ele puder ter vazado ou como medida de segurança de rotina.

• Painel: abra o menu de ações, selecione Webhook secret e depois Reset. O novo segredo é mostrado uma única vez.
• API: chame Fazer a rotação do segredo de assinatura. A resposta contém o novo secret. Obter um webhook também retorna o segredo atual.

O segredo antigo deixa de funcionar imediatamente, e todas as requisições a partir de então, incluindo as novas tentativas de eventos mais antigos, são assinadas com o novo. Para fazer a rotação sem rejeitar requisições, faça o seu endpoint aceitar qualquer um dos dois segredos por alguns minutos, redefina o segredo, faça deploy do novo valor e depois remova o antigo.

Confirmar que funcionou

1. Envie um evento de teste e confirme que o seu endpoint retorna 2xx.
2. Envie um e-mail real ou dispare o evento em que você se inscreveu.
3. Na aba Requests do webhook, a requisição aparece como Delivered. O horário Last used do webhook é atualizado.

Veja também