# Configurar um webhook

> Crie um endpoint de webhook, escolha os eventos dele, adicione filtros de payload, envie um evento de teste e ative, desative ou faça a rotação do segredo.

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](/pt/docs/api-reference/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](/pt/docs/webhooks/request-signature/).
- 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

**Painel**

  1. **Abra a página Webhooks.** Acesse **Email API → Webhooks** e selecione **Add webhook**.

  2. **Informe um nome e uma URL.** O nome deve ser único no workspace, por exemplo `Production events`. A URL é o seu endpoint, por exemplo `https://acme.com/webhooks/emailit`. Selecione **Create**.

  3. **Copie o segredo.** A caixa de diálogo mostra o segredo do webhook, que começa com `whsec_`, junto com o aviso “You can see the webhook secret only once. Store it safely.” Copie-o para o ambiente da sua aplicação, por exemplo como `EMAILIT_WEBHOOK_SECRET`, e selecione **Done**.

  Um webhook criado no painel fica inscrito em todos os tipos de evento. A aba **Settings** do webhook é aberta para que você possa restringi-lo.

**API**

  Chame [Criar um webhook](/pt/docs/api-reference/webhooks/create/). Liste os tipos de evento em `events` ou defina `all_events` como `true`. A resposta `201` inclui o `secret`.

```bash
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"]
  }'
```

  Ao contrário do painel, a API usa por padrão `all_events: false` e uma lista `events` vazia, então um webhook criado sem nenhum dos dois não recebe nada. Um nome duplicado retorna `409`; atingir o limite de endpoints do seu plano retorna `422` com `usage.used` e `usage.limit`.

## Escolher os eventos

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

**Painel**

  Na aba **Settings** do webhook, desative **All events** e selecione os tipos no card **Events**. Os eventos são agrupados por recurso (**Emails**, **Domains**, **Audiences**, **Subscribers**, **Contacts**, **Templates**, **Suppressions**, **Email Verifications**, **Email Verification Lists**), e cada grupo tem uma caixa **Select all**. Selecione **Save**.

  O seletor não lista todos os tipos que o Emailit envia. `email.canceled`, `email.held`, `email.unsubscribed`, `email.resubscribed`, `subscriber.resubscribed` e os eventos `campaign.*` chegam aos webhooks que têm **All events** ativado, ou você pode adicioná-los à lista pela API. O grupo **Deprecated** reúne nomes de eventos antigos que não são mais enviados. Consulte [Tipos de evento](/pt/docs/webhooks/event-types/).

**API**

  Chame [Atualizar um webhook](/pt/docs/api-reference/webhooks/update/). `events` substitui a lista inteira. Definir `all_events` como `true` limpa a lista.

```bash
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

Pro, Business, Custom

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.

| Operador | Corresponde quando o campo |
| --- | --- |
| `equals` / `not_equals` | É / não é exatamente o valor. |
| `contains` / `not_contains` | Contém / não contém o valor. |
| `starts_with` / `ends_with` | Começa / termina com o valor. |
| `greater_than` / `less_than` | É um número maior / menor que o valor. |
| `is_set` / `is_not_set` | Tem um valor não vazio / está ausente ou vazio. Não precisa de valor. |
| `in` / `not_in` | É igual / não é igual a um dos valores de um array. Envie o array pela API, como no exemplo abaixo. |

**Painel**

  Na aba **Settings** do webhook, localize o card **Filter**. Escolha o modo de correspondência, adicione regras com campo, operador e valor e selecione **Save**. Deixe as regras vazias para entregar todos os eventos inscritos. No Pay as you go, o card fica bloqueado e mostra **Upgrade**.

**API**

  Envie `filter` com [Criar um webhook](/pt/docs/api-reference/webhooks/create/) ou [Atualizar um webhook](/pt/docs/api-reference/webhooks/update/). Defina-o como `null` para removê-lo. No Pay as you go, um filtro retorna `403` com `"error": "plan_required"`.

```bash
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:

| Objetivo | Regra |
| --- | --- |
| Apenas e-mails recebidos em um endereço | `to` `equals` `support@inbound.acme.com` |
| Apenas um domínio de remetente | `from` `ends_with` `@billing.acme.com` |
| Apenas e-mails que você marcou com metadados | `meta.source` `equals` `checkout` |
| Apenas cliques na sua página de preços | `link.url` `starts_with` `https://acme.com/pricing` |
| Apenas e-mails que trazem um ID de cliente | `meta.customer_id` `is_set` |

> **Os campos variam entre os tipos de evento:** Uma regra sobre um campo que o evento não tem nunca corresponde. Os eventos de status de e-mail têm `to` e `from` no nível superior, mas os eventos de clique e de carregamento os aninham como `email.rcpt_to` e `email.mail_from`, e os eventos de contato têm `email`. Com **All rules match**, um webhook filtrado por `to` descarta silenciosamente todos os cliques. Use webhooks separados para cada tipo de evento, ou **Any rule matches** com uma regra para cada formato. Confira os nomes dos campos na [referência de eventos](/pt/docs/webhooks/event-types/).

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.

**Painel**

  Na página do webhook, abra o menu de ações (**…**) e selecione **Send test**. Escolha um tipo de evento e selecione **Send test**. A caixa de diálogo mostra “Your endpoint returned 200” (ou o status que o seu endpoint retornou) e o corpo da resposta. “Could not reach the endpoint” significa que a requisição não recebeu uma resposta HTTP, por exemplo por causa de um erro de DNS, um timeout ou um redirecionamento.

**API**

  Chame [Enviar um evento de teste](/pt/docs/api-reference/webhooks/test/) com qualquer tipo de evento.

```bash
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"}'
```

  A resposta tem `ok`, `status_code`, `body` (a resposta do seu endpoint, com até 2.000 caracteres), `type` e o `payload` que foi enviado.

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](/pt/docs/webhooks/event-types/) 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](/pt/docs/api-reference/webhooks/update/) 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](/pt/docs/logs/events/#reconcile-missed-webhook-events). O Emailit também desativa webhooks automaticamente após 3 dias de falhas; consulte [Novas tentativas e falhas](/pt/docs/webhooks/retries-and-failures/).

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](/pt/docs/api-reference/webhooks/reset-secret/). A resposta contém o novo `secret`. [Obter um webhook](/pt/docs/api-reference/webhooks/get/) 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

  - [Verificar assinaturas](/pt/docs/webhooks/request-signature/)
  - [Requisições de webhook](/pt/docs/webhooks/webhook-requests/)
  - [Tipos de evento](/pt/docs/webhooks/event-types/)
  - [Novas tentativas e falhas](/pt/docs/webhooks/retries-and-failures/)

---
Fonte: https://emailit.com/pt/docs/webhooks/set-up/