Validação de Webhooks

Visão Geral

A API FullPix envia notificações automáticas sobre mudanças de status de transações através de webhooks. Para garantir a segurança e autenticidade dessas notificações, implementamos um sistema de assinatura HMAC SHA-256.

Como Funciona

1. Configuração do Webhook Secret

Ao criar uma transação, você pode fornecer um webhookSecret (string secreta) que será usado para assinar todos os webhooks relacionados àquela transação.

Exemplo de criação de transação com webhook:

{
  "paymentMethod": "PIX",
  "amount": 10000,
  "postbackUrl": "https://seu-site.com/webhook",
  "webhookSecret": "sua_chave_secreta_aqui_123456",
  "customer": { ... },
  "items": [ ... ]
}

2. Recebimento do Webhook

Quando o status da transação mudar (ex: pagamento confirmado), a API enviará um POST para a URL configurada em postbackUrl com:

Headers:

Content-Type: application/json
X-Webhook-Signature: sha256=a1b2c3d4e5f6...

Body:

{
  "id": "txn_abc123def456",
  "status": "paid",
  "amount": 10000,
  "paymentMethod": "PIX",
  "customer": { ... },
  "items": [ ... ],
  ...
}

3. Validação da Assinatura

A assinatura no header X-Webhook-Signature é uma hash HMAC SHA-256 do corpo do webhook (payload JSON).

Para validar:

Extraia a assinatura do header X-Webhook-Signature (remova o prefixo sha256=)

Calcule a assinatura esperada usando seu webhookSecret

Compare as assinaturas de forma segura (timing-safe)

Exemplos de Implementação

Node.js / Express

Python / Flask

PHP

Go

Boas Práticas

✅ Recomendações

Sempre valide a assinatura antes de processar o webhook

Use comparação timing-safe para evitar timing attacks

Armazene o webhook secret de forma segura (variáveis de ambiente, cofre de senhas)

Use HTTPS para sua URL de webhook

Processe webhooks de forma idempotente (mesma transação pode gerar múltiplos webhooks)

Responda rapidamente (200 OK) e processe de forma assíncrona se necessário

Mantenha logs de webhooks recebidos para auditoria

❌ Evite

Não use HTTP (sem TLS) para receber webhooks

Não exponha o webhook secret em código cliente ou logs

Não confie apenas no IP de origem para validação

Não faça processamento pesado antes de responder 200 OK

Não use comparação simples de strings (==, ===) para validar assinaturas

Testando Webhooks Localmente

Para testar webhooks em desenvolvimento, você pode usar ferramentas como:

ngrok: Túnel HTTPS para localhost

LocalTunnel: Alternativa ao ngrok

Webhook.site: Receber e inspecionar webhooks online

Eventos de Webhook

Webhooks são disparados nos seguintes eventos:

Evento	Status	Descrição
Aguardando Pagamento	`waiting_payment`	PIX gerado, aguardando pagamento
Pagamento Confirmado	`paid`	Pagamento aprovado e confirmado
Pagamento Recusado	`refused`	Pagamento negado (saldo, antifraude, etc)
Reembolso	`refunded`	Transação reembolsada

Suporte

Para dúvidas ou problemas com webhooks:

📧 Email: contato@fullpix.com.br

🐛 Issues: Reporte bugs através do suporte

Segurança

⚠️ IMPORTANTE: O webhookSecret é sensível e deve ser tratado como uma senha. Nunca o compartilhe publicamente ou o comite em repositórios de código.

Se você suspeitar que seu webhook secret foi comprometido, entre em contato com o suporte imediatamente para gerar um novo.

Visão Geral#

Como Funciona#

1. Configuração do Webhook Secret#

2. Recebimento do Webhook#

3. Validação da Assinatura#

Exemplos de Implementação#

Node.js / Express#

Python / Flask#

PHP#

Go#

Boas Práticas#

✅ Recomendações#

❌ Evite#

Testando Webhooks Localmente#

Eventos de Webhook#

Suporte#

Segurança#