Webhooks - Kourio

Cada evento de entrega vira uma chamada POST no seu endereço: aceita, entregue, adiada, devolvida, reclamada.

Confira a assinatura

Toda entrega vai assinada em kourio-signature. Confira antes de confiar no corpo — sem isso, qualquer um que descubra a sua URL pode forjar um evento e, por exemplo, marcar um pedido como entregue.

import { verifyWebhookSignature } from '@kourio/sdk';

app.post('/webhooks/kourio', async (req, res) => {
  const valida = verifyWebhookSignature({
    payload: req.rawBody,          // o corpo cru, antes de virar objeto
    signature: req.headers['kourio-signature'],
    secret: process.env.KOURIO_WEBHOOK_SECRET!,
  });
  if (!valida) return res.status(401).end();

  res.status(200).end();          // responda rápido; processe depois
});

Use o corpo cru. Se você validar a assinatura sobre o objeto já convertido e reserializado, a ordem das chaves ou um espaço a mais mudam os bytes e a conferência falha por um motivo que não tem nada a ver com segurança.

Responda rápido

Responda 200 assim que receber e processe depois. Um endpoint lento vira tentativa repetida, e tentativa repetida vira evento duplicado no seu sistema. Trate os eventos como pelo menos uma vez: o mesmo evento pode chegar duas vezes. O id do evento é o que permite ignorar a segunda.

Quando um evento não chega

GET /v1/webhooks/{id}/deliveries traz cada tentativa com o código e o corpo que o seu servidor devolveu. É o que responde “por que não chegou” sem depender do seu log.