PT EN

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 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#