Segurança de Webhooks

Toda entrega da Malvo inclui o header Malvo-Signature. Verifique o HMAC do corpo HTTP cru antes de aplicar qualquer efeito. Headers customizados e o IP de egress estático continuam válidos como defesa em profundidade. Aplicações criadas após este lançamento já nascem com um signing secret. Aplicações existentes têm um prazo de adequação publicado no Dashboard (90 dias). A Malvo não interrompe entregas depois do prazo — o modelo antigo (só headers + IP) deixa de ser suficiente.

HMAC (`Malvo-Signature`)

Formato:

Malvo-Signature: t=<unix>,v1=<hex>

A assinatura é HMAC-SHA256 de {t}.{raw body}, hex minúsculo, com o signing secret da aplicação (whsec_…). Durante uma rotação o header pode trazer dois v1. Use os bytes exatos do POST — nunca JSON.parse + JSON.stringify. Vetor de teste:

secret  = whsec_testsecret
t       = 1700000000
body    = {"event":"item/created","eventId":"evt_1","link":"https://a.test/?x=1&y=2"}
v1      = dcaf77c8756a00f70a8dd760e8c84b6d7f165f6ab0b697bfa3b13c240634e6f2

Copie o secret em Dashboard → Webhooks → Revelar segredo. Ele não volta em GET /webhooks. Durante uma rotação o SDK aceita os dois secrets:

verifyWebhookSignature(body, header, [secretAtual, secretAnterior]);

A janela de replay padrão é 5 minutos. Cada reentrega da Malvo assina com t fresco, então retries de até ~3 h continuam válidos. Deduplique por eventId — o HMAC não substitui isso. Quem não usa o SDK: HMAC-SHA256 de "{t}." + raw_body com a string inteira do secret (incluindo whsec_), compare em tempo constante, aceite qualquer v1 do header.

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:

Na API pública, o mapa é aceito em POST /webhooks e PATCH /webhooks/{id} e não volta em nenhum GET/list.
No Dashboard, owners e admins veem e editam os headers do endpoint. O signing secret HMAC é outro material — mora na aplicação e só aparece ao revelar na página Webhooks.
Não coloque o signing secret HMAC nesse mapa: a Malvo já envia Malvo-Signature.

Rotação dos headers customizados via PATCH

Pela API pública a rotação do mapa é um PATCH que reescreve os headers:

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 pública do PATCH confirma a atualização mas não ecoa os headers. No Dashboard você edita o mapa na ficha do endpoint. A rotação do signing secret HMAC é o botão Rotacionar da página Webhooks (o previous vale 24 h).

Rotação do signing secret

No Dashboard → Webhooks, Rotacionar gera um secret novo e mantém o anterior por 24 h.
No receiver, passe os dois para verifyWebhookSignature enquanto migra.
Encerrar anterior invalida o secret antigo na hora. Uma segunda rotação com previous ainda válido retorna 409.

IP allowlisting

Todas as entregas saem de um único IP de egress estático. Liberar esse IP no firewall/WAF é defesa extra, não substitui o HMAC.

O IP de egress ainda não é exibido na página Webhooks do Dashboard. Confirme o valor vigente com o suporte da Malvo — não invente nem reutilize um IP de outra fonte.

Checklist de validação do receiver

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

HMAC

Malvo-Signature confere com o signing secret da aplicação sobre o corpo cru.

IP de origem

O IP de origem é o egress estático da Malvo (valor vigente via suporte, até o Dashboard publicar).

Header de autenticação

O header de auth customizado bate com o segredo configurado, se você usa um.

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: o t do HMAC expira em 5 minutos; cada retry da Malvo traz um t novo. Persista o eventId e trate duplicatas como no-op. Não rejeite o evento pela idade do outbox.

Handler de exemplo

O padrão é: HMAC → parse → idempotência → 200 → processar async. Use express.raw (ou o equivalente no seu framework). express.json() consome o body e o HMAC quebra.

import {
  verifyWebhookSignature,
  parseWebhookEvent,
  WebhookSignatureError,
} from "@malvo/server";

app.post("/webhooks/malvo", express.raw({ type: "application/json" }), async (req, res) => {
  const secret = process.env.MALVO_WEBHOOK_SECRET;
  const previous = process.env.MALVO_WEBHOOK_SECRET_PREV;
  if (!secret) return res.sendStatus(500);

  try {
    verifyWebhookSignature(
      req.body,
      req.header("malvo-signature") ?? "",
      previous ? [secret, previous] : secret,
    );
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.sendStatus(401);
    throw err;
  }

  const evt = parseWebhookEvent(JSON.parse(Buffer.from(req.body).toString("utf8")));
  if (await alreadySeen(evt.eventId)) return res.sendStatus(200);
  await queue.add("malvo", evt, { jobId: evt.eventId });
  return res.sendStatus(200);
});

401 na assinatura faz a Malvo reentregar (útil se o relógio do receiver atrasou). Secret errado ou express.json() no lugar de .raw() também geram 9 retries — corrija o receiver, não o cadastro do webhook.

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` / `invalid webhook signature`	Body parseado (`express.json`), secret errado, ou relógio > 5 min	Use o corpo cru; confira o secret no Dashboard; NTP
Entregas 9× com HMAC falhando	Receiver 401 em todo retry	O `t` é fresco a cada tentativa — o problema é body/secret, não a idade do evento
401/403 do receiver no IP da plataforma	Header de auth customizado ausente ou rotacionado	Re-defina os `headers` no Dashboard ou via `PATCH /webhooks/{id}`
Não acha o IP de egress no Dashboard	Ainda não é publicado na página Webhooks	Peça o valor vigente ao suporte da Malvo
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

HMAC (`Malvo-Signature`)

Headers customizados por webhook

Rotação dos headers customizados via PATCH

Rotação do signing secret

IP allowlisting

Checklist de validação do receiver

Handler de exemplo

Troubleshooting de entrega

Próximos passos

Entrega & Retry

Referência — Webhooks

​HMAC (Malvo-Signature)

​Headers customizados por webhook

​Rotação dos headers customizados via PATCH

​Rotação do signing secret

​IP allowlisting

​Checklist de validação do receiver

​Handler de exemplo

​Troubleshooting de entrega

​Próximos passos

Entrega & Retry

Referência — Webhooks

HMAC (`Malvo-Signature`)

Headers customizados por webhook

Rotação dos headers customizados via PATCH

Rotação do signing secret

IP allowlisting

Checklist de validação do receiver

Handler de exemplo

Troubleshooting de entrega

Próximos passos