Testes e solução de problemas

Roteiro para validar sua integração e tabela de diagnóstico dos problemas mais comuns.

Roteiro de testes

1. 1. Autenticação

   Token com chaves corretas (200); com chave errada (401); sem cabeçalho (401). Renove o token ao receber 401.

2. 2. Webhook

   PUT /api/webhook → POST /api/webhook/test → confira no seu receptor e em GET /api/webhook/deliveries. Teste também assinatura inválida e timestamp antigo (devem ser rejeitados).

3. 3. Criação

   Crie com dados válidos; com campo faltando (422); com valor 0 ou negativo (422); com método desabilitado (400).

4. 4. Idempotência

   Repita a mesma chamada com a mesma chave: mesma resposta e Idempotent-Replayed: true. Troque o corpo mantendo a chave: 422.

5. 5. Estados

   Simule no seu código eventos invoice.paid, duplicado e fora de ordem. O pedido deve ser liberado uma única vez.

6. 6. Falhas

   Force timeout, 429 e 500 no seu cliente (mocks) e confira o backoff e a reutilização da chave.

Teste unitário da assinatura

Use o vetor de teste da página de Webhooks. Exemplo em Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';
import assert from 'node:assert/strict';

const assinar = (segredo, t, corpo) => createHmac('sha256', segredo).update(`${t}.${corpo}`).digest('hex');

const v1 = assinar('whsec_test_secret', 1700000000, '{"id":"evt_test","type":"ping"}');
assert.equal(v1, '76e93d7667b36f8aab799377027b5ad5c17365edfaca34f11cc7c9f570f94a2a');
assert.ok(timingSafeEqual(Buffer.from(v1), Buffer.from(v1)));
console.log('ok');

Problemas comuns