Implementação

Exemplos CompletosCopy Anchor Link

Os exemplos abaixo recebem os eventos de transação, validam a assinatura X-Avista-Signature, respondem 2xx rapidamente e evitam processamento duplicado. A geração da chave e os detalhes da assinatura estão em Assinatura HMAC.

Assinatura HMAC (X-Avista-Signature)Copy Anchor Link

Depois que você gera a chave de assinatura no painel, todo webhook enviado para a sua conta inclui o header X-Avista-Signature com o HMAC-SHA256, em hexadecimal, do corpo bruto da requisição, calculado com essa chave. Validar a assinatura garante que o webhook veio da Gateways (e não de um terceiro que descobriu sua URL) e que o payload não foi alterado em trânsito.

Gerando e rotacionando a chaveCopy Anchor Link

A chave é gerada e rotacionada somente pelo painel (https://<dashboard-host>); não há endpoint de API para isso.

export PIX_API_WEBHOOK_SECRET=<chave-gerada-no-painel>

Rotação sem rejeitar webhooks em trânsitoCopy Anchor Link

A rotação substitui a chave imediatamente: os webhooks enviados a partir daí usam a nova chave. Webhooks que já estavam na fila podem ainda chegar assinados com a chave anterior. Por isso, durante a troca, aceite as duas chaves por cerca de 30 minutos:

const SECRETS = [
  process.env.PIX_API_WEBHOOK_SECRET_CURRENT,
  process.env.PIX_API_WEBHOOK_SECRET_PREVIOUS,
].filter(Boolean) as string[];

function isValid(rawBody: Buffer, received: string): boolean {
  const b = Buffer.from(received, 'hex');
  return SECRETS.some((secret) => {
    const a = Buffer.from(
      crypto.createHmac('sha256', secret).update(rawBody).digest('hex'),
      'hex',
    );
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  });
}

Depois desse período, remova PIX_API_WEBHOOK_SECRET_PREVIOUS. Rotacione quando houver suspeita de vazamento ou em rotações programadas (por exemplo, a cada 90 dias).

Como validarCopy Anchor Link

A assinatura cobre exatamente o corpo bruto da requisição (rawBody), em UTF-8, antes de qualquer JSON.parse. Se você reserializar o objeto recebido para calcular o HMAC, qualquer divergência (ordem de chaves, espaços, encoding) fará a assinatura não bater.

Headers customizadosCopy Anchor Link

Os headers customizados cadastrados na URL (até 5) são enviados em todo webhook, junto com a assinatura. Se você já valida um header próprio (por exemplo, Authorization: Basic ...), pode continuar validando: o X-Avista-Signature é adicional e não substitui esses headers.

IdempotênciaCopy Anchor Link

Para eventos de transação, use como chave a combinação event + transactionId + status. Assim, uma mesma transação que mude de status gera um novo processamento, e repetições do mesmo evento são ignoradas. Para eventos MED, use medId + event.

const key = `webhook:${payload.event}:${payload.transactionId}:${payload.status}`;

const isNew = await redis.set(key, '1', 'EX', 86400, 'NX');

if (!isNew) {
  console.log('Webhook já processado, ignorando');
  return;
}

await processWebhook(payload);

Boas PráticasCopy Anchor Link

RetentativasCopy Anchor Link

Se o seu endpoint não responder com 2xx em até 10 segundos (ou se a conexão falhar), a entrega é retentada:

Códigos de RespostaCopy Anchor Link

Seu endpoint deve retornar um código HTTP apropriado:

Próximos PassosCopy Anchor Link