Segurança de Webhooks

A Malvo não assina os payloads de webhook com HMAC. Em vez disso, a autenticidade de uma entrega é garantida por dois mecanismos combinados: headers customizados e IP allowlisting.

Headers customizados por webhook

Cada webhook pode carregar um mapa de headers (nome → valor) que é enviado verbatim em toda entrega. É aí que você coloca o seu segredo compartilhado.

POST /webhooks/malvo HTTP/1.1
Host: api.your-app.com
Content-Type: application/json
Authorization: Bearer <seu-segredo-compartilhado>
X-CLIENT-ID: <secret>

Propriedades importantes dos headers:

Write-only. São aceitos no POST /webhooks e no PATCH /webhooks/{id}, mas nunca retornados em nenhum GET/list e nunca exibidos no Dashboard.
Somente via API. Não há como definir ou ler headers pela UI — apenas administradores e owners editam webhooks no Dashboard, e ainda assim os headers ficam ocultos.

Rotação de segredos via PATCH

Como os headers são write-only, a rotação do segredo é feita por um PATCH que reescreve o mapa:

curl -X PATCH https://api.malvo.io/webhooks/39e1d11f-3c12-44a8-a788-75c5747e1a8e \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "headers": { "Authorization": "Bearer <segredo-rotacionado>" }
  }'

{
  "id": "39e1d11f-3c12-44a8-a788-75c5747e1a8e",
  "event": "all",
  "url": "https://api.your-app.com/webhooks/malvo",
  "createdAt": "2026-06-10T12:00:00.000Z",
  "updatedAt": "2026-06-10T12:05:00.000Z",
  "disabled": null
}

A resposta do PATCH confirma a atualização mas não ecoa os headers de volta. Esse é o único caminho de rotação — os headers não podem ser editados pelo Dashboard por design.

IP allowlisting

Todas as entregas saem de um único IP de egress estático. Adicione esse IP à allowlist do seu firewall/WAF para que apenas a Malvo consiga atingir o seu receiver.

O IP de egress estático único está disponível no seu Dashboard, na seção Webhooks. Use sempre o valor publicado lá — não codifique um IP a partir de qualquer outra fonte.

Checklist de validação do receiver

Valide toda requisição recebida nesta ordem, antes de aplicar qualquer efeito:

IP de origem

O IP de origem é igual ao IP de egress estático publicado no Dashboard.

Header de autenticação

O header de auth customizado bate com o segredo configurado.

Corpo e evento

O corpo é JSON válido e event é um valor que você assina.

Idempotência

O eventId ainda não foi processado (deduplique — veja Entrega & Retry).

Proteção contra replay: persista o eventId e trate duplicatas como no-op. Opcionalmente, embuta um claim de timestamp no segredo/JWT e rejeite eventos mais antigos que ~10 minutos — mas calibre para a janela de retry de até ~3h.

Handler de exemplo

O padrão é: validar → enfileirar → responder 200 → processar async.

app.post('/webhooks/malvo', async (req, res) => {
  // 1. validar IP de origem (no proxy/WAF) e header de auth
  if (req.headers.authorization !== `Bearer ${SECRET}`) {
    return res.sendStatus(401);
  }

  const evt = req.body;

  // 2. idempotência: no-op se já visto
  if (await alreadySeen(evt.eventId)) return res.sendStatus(200);

  // 3. enfileirar (dedupe por eventId) e responder 200 em <5s
  await queue.add('malvo', evt, { jobId: evt.eventId });
  return res.sendStatus(200);

  // 4. o processamento pesado roda no worker, fora do ciclo da request
});

Responda 2XX antes do trabalho pesado. Processamento síncrono antes do 200 estoura o limite de 5 segundos e a Malvo passa a reentregar o mesmo evento até 9 vezes.

Troubleshooting de entrega

Sintoma	Causa provável	Correção
Webhook não chega	URL é `http://`/`localhost`, ou está atrás de VPN privada	Use URL HTTPS pública (ngrok em dev)
Webhook para após ~90 dias	Auto-remoção de URLs de ferramentas de teste	Recrie com uma URL de produção
`Webhook limit reached`	Mais de 5 webhooks para o mesmo evento	Consolide; use `event: "all"`
Endpoint dá timeout, reentregue 9×	Trabalho pesado síncrono antes de responder	Confirme primeiro, processe async
Entregas repetidas para o mesmo `eventId`	Endpoint retornou não-2XX, ou levou >5s	Reduza a latência; deduplique por `eventId`
401/403 do receiver no IP da plataforma	Header de auth ausente ou rotacionado	Re-defina os `headers` via `PATCH /webhooks/{id}`
Não dá para editar `headers` no Dashboard	Por design — material sensível	Use somente a API
5xx do receiver	—	A plataforma reentrega pelo schedule de 9 tentativas, depois descarta
200 retornado, mas processamento duplicado	Receiver não deduplica	Persista o `eventId` e trate duplicatas como no-op
Eventos chegam fora de ordem	Comportamento normal	Nunca assuma ordem; re-busque o recurso canônico

Próximos passos

Entrega & Retry

O schedule de retry, idempotência e a reconciliação noturna.

Referência — Webhooks

POST, GET, PATCH e DELETE de webhooks, incluindo o campo headers.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Segurança de Webhooks

Headers customizados por webhook

Rotação de segredos via PATCH

IP allowlisting

Checklist de validação do receiver

Handler de exemplo

Troubleshooting de entrega

Próximos passos

Entrega & Retry

Referência — Webhooks

​Headers customizados por webhook

​Rotação de segredos via PATCH

​IP allowlisting

​Checklist de validação do receiver

​Handler de exemplo

​Troubleshooting de entrega

​Próximos passos

Entrega & Retry

Referência — Webhooks

Headers customizados por webhook

Rotação de segredos via PATCH

IP allowlisting

Checklist de validação do receiver

Handler de exemplo

Troubleshooting de entrega

Próximos passos