Webhook de status

​

Configuração

• A URL precisa ser https e pública. Não são aceitos endereços privados, de loopback ou internos, nem credenciais na URL (https://usuario:senha@...).
• Trocar a URL depois mantém o mesmo segredo.

• Em Gerar novo segredo, você cria um novo segredo a qualquer momento. O segredo anterior deixa de valer na hora, inclusive para as novas tentativas de entregas pendentes: atualize o seu sistema logo em seguida.
• Em Remover webhook, você apaga a URL e o segredo e descarta as entregas pendentes. Um novo cadastro gera um novo segredo.
• As mudanças da URL ficam registradas na aba Histórico.

​

Eventos

​

Evento de teste

• O teste não tem novas tentativas: o dashboard mostra na hora se o seu serviço respondeu com 2xx ou qual foi a falha (por exemplo, 405 quando a URL não aceita POST, ou ausência de resposta no prazo).
• O teste é assinado com um segredo descartável, e não com o seu. Se o seu serviço valida a assinatura, ele vai recusar o teste (por exemplo, com 401 ou 403): nesse caso a recusa é esperada e confirma que a URL está acessível.
• Ignore eventos webhook.test no processamento dos seus pedidos.

​

Headers da chamada

​

Corpo

{
  "id": "6f1c2c1e-6a43-4f0e-9a51-0d6f5c1b2a77",
  "type": "transaction.status_changed",
  "createdAt": "2026-10-07T13:05:01.120Z",
  "data": {
    "transactionId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "orderNumber": "PED-9981",
    "status": "approved",
    "previousStatus": "pending",
    "reason": null,
    "flowType": "default",
    "sequence": 2,
    "occurredAt": "2026-10-07T13:05:00.987Z"
  }
}

​

Como verificar a assinatura

1. Leia o corpo cru da requisição, exatamente os bytes recebidos. Não use o JSON depois de convertido e serializado de novo.
2. Monte o texto <x-trustpass-timestamp>.<corpo cru> e calcule o HMAC-SHA256 com o seu segredo, em hexadecimal.
3. Compare v1=<hmac> com o header x-trustpass-signature usando uma comparação em tempo constante.
4. Rejeite timestamps muito antigos (por exemplo, mais de 5 minutos) para se proteger contra reenvio da mesma chamada.

const crypto = require('node:crypto');

function isValidSignature(rawBody, headers, secret) {
  const timestamp = Number(headers['x-trustpass-timestamp']);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return false;
  }

  const expected =
    'v1=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  const received = String(headers['x-trustpass-signature'] ?? '');

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

​

Resposta, timeout e novas tentativas

• Qualquer resposta 2xx confirma a entrega. Responda rápido e processe o evento depois.
• Cada tentativa tem timeout de 5 segundos. Redirecionamentos não são seguidos e contam como falha.
• A primeira tentativa sai em poucos segundos após a mudança de status. Se ela falhar (resposta fora de 2xx, timeout ou erro de rede), há novas tentativas depois de 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, 6 h, 12 h e 24 h: 10 tentativas, cerca de 47 horas no total. Esgotadas as tentativas, o evento não é mais reenviado.

​

Duplicidade e ordem

• Descarte duplicados pelo x-trustpass-event-id.
• Guarde o último sequence aplicado por transação e ignore eventos com sequence menor ou igual a ele.