# Boas práticas para receptores de webhooks

Verifique o corpo em bruto, responda em menos de 10 segundos, elimine duplicados pelo webhook-id, descarte alterações antigas com data.resource.sequence, escolha bem o código de estado e rode segredos com sobreposição.


O processo de entrega foi feito para poder repetir sem riscos, o que significa que o seu receptor vai por vezes receber a mesma entrega duas vezes e tem de lidar com isso. As regras abaixo decorrem do comportamento real desse processo.

## Verificar antes de interpretar

Calcule a assinatura sobre os bytes recebidos, e não sobre um JSON que interpretou e voltou a serializar: a ordem das chaves e os espaços alteram o resultado. Recuse um `webhook-timestamp` com mais de alguns minutos. A [página de verificação](/docs/webhooks/verify) tem código para Node.js, Python e Go.

## Responder depressa, processar depois

O processo de entrega espera no máximo 10 segundos pela resposta e depois dá a tentativa como falhada. Guarde o corpo, responda `200` e faça o trabalho demorado (actualizar o ERP, enviar emails) a partir da sua própria fila.

## Eliminar duplicados pelo webhook-id

O `webhook-id` é o identificador `dlv_` da entrega. Mantém-se igual nas novas tentativas automáticas, num **Reenviar** manual e num reenvio em lote. Guarde os identificadores já tratados e ignore os repetidos. Se vários endereços seus subscreverem o mesmo evento, cada um recebe a sua própria entrega; nesse caso, a chave comum é o `id` do evento (`wev_`).

```javascript
app.post("/hooks/billing", express.raw({ type: "application/json" }), async (req, res) => {
  const valid = verifyWebhook(req.body.toString("utf8"), req.headers, process.env.WEBHOOK_SECRET);
  if (valid === false) return res.status(401).end();
  const deliveryId = req.headers["webhook-id"];
  if (await seen.has(deliveryId)) return res.status(200).end();
  const event = JSON.parse(req.body);
  const last = await sequences.get(event.data.resource.type, event.data.resource.id);
  if (event.data.resource.sequence > (last ?? 0)) {
    await jobs.enqueue(event);
  }
  await seen.add(deliveryId);
  res.status(200).end();
});
```

## Confiar na sequência, não na hora de chegada

Para o mesmo endereço, as entregas sobre um registo seguem por ordem: a seguinte espera enquanto a anterior estiver pendente ou guardada, e segue quando essa for concluída, falhar ou for cancelada. Registos diferentes não esperam uns pelos outros, e uma entrega guardada ou reenviada pode chegar depois de já ter avançado. `data.resource.sequence` conta os eventos de cada registo; ignore o que não for mais recente do que aquilo que já aplicou, ou leia o registo na API quando precisar do estado actual.

## Escolher o código de estado de propósito

`5xx`, `408`, `425` e `429` significam "tente mais tarde". Qualquer outro `4xx` pára a entrega ao fim de duas tentativas e guarda-a como `paused`. `410 Gone` pausa o endereço inteiro e guarda tudo o que estava na fila para ele. Responda `410` apenas quando quiser mesmo deixar de receber.

## Rodar segredos com sobreposição

```bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ/roll" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds": 86400}'
```

```json
{
  "id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "url": "https://erp.example.test/hooks/billing",
  "description": "Sincronização da facturação com o ERP",
  "events": ["invoice.paid", "payment.received"],
  "enabled": true,
  "secret": "whsec_vQPM6Bhi6UrlK4RSGJDD11Kz8F6kc5T8pC/smJkBVPA=",
  "created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
  "created_at": "2026-11-19T08:02:41.118204Z",
  "updated_at": "2026-11-19T11:40:03.551870Z",
  "previous_secret_expires_at": "2026-11-20T11:40:03.551870Z",
  "health": "healthy",
  "consecutive_failures": 0,
  "api_version": "v1"
}
```

Até `previous_secret_expires_at`, o cabeçalho `webhook-signature` leva uma assinatura `v1,` por segredo, separadas por um espaço, para que um receptor com qualquer dos dois segredos continue a aceitar as entregas. Sem corpo no pedido, a sobreposição é de 24 horas; `overlap_seconds` vai de `0` (o segredo antigo deixa de valer de imediato) a `604800` (7 dias). No painel, esta acção chama-se **Rodar segredo**.

## Recuperar depois de uma falha

Por omissão, os eventos ficam disponíveis durante 90 dias. `GET $BUSINESS_API/developer/events` aceita `type`, `resource_type`, `resource_id`, `from` e `to`, o que permite comparar o que guardou com o que aconteceu.

## Próximos passos

- [O calendário de novas tentativas e a saúde do endereço](/docs/webhooks/retries)
- [Testar o receptor no sandbox](/docs/webhooks/testing)
- [Notas de actualização para os cabeçalhos Standard Webhooks](/docs/upgrades/2026-11-19-standard-webhooks)

