Pular para o conteúdo principal

Callbacks (Webhooks dos Provedores)

Os provedores de gateway enviam notificações ao sistema quando o status de pagamentos muda. Essas notificações são processadas de forma assíncrona.

Endpoints de Callback​

Kobana​

POST /api/callbacks/kobana

Header de Assinatura: X-Kobana-Signature: sha256=<hex>

Eventos recebidos:

  • pix.register.confirmed / error / failed / requested
  • pix.paid
  • bank_billet.register.confirmed / error / failed / requested
  • bank_billet.paid

Pagar.me​

POST /api/callbacks/pagarme

Header de Assinatura: x-hub-signature: sha256=<hex>

Eventos recebidos:

  • order.* (paid, payment_failed, created, canceled, closed, updated)
  • charge.* (paid, payment_failed, refunded, pending, processing, etc.)
  • card.* (created, updated, deleted, expired)

Fluxo de Processamento​

Recebe POST do provedor
  → Valida assinatura HMAC-SHA256
  → Verifica chave de idempotência (ignora duplicados)
  → Cria registro de Callback (status=pending)
  → Enfileira job para processamento assíncrono
  → Retorna 200 imediatamente

Processamento Assíncrono​

Worker processa a fila
  → Roteia para o handler do provedor
  → Mapeia status do provedor para status interno
  → Atualiza registro de pagamento
  → Cria evento para notificação
  → Atualiza Callback (status=completed)

Segurança​

  • Validação de assinatura: HMAC-SHA256 com comparação timing-safe
  • Idempotência: Chave única [provider, idempotencyKey] previne duplicação
  • Retries: Máximo de 5 tentativas com backoff exponencial
  • Retenção: Callbacks falhos mantidos por 7 dias

Registro de Callback​

Cada callback recebido é registrado com:

  • Provedor de origem
  • Chave de idempotência
  • Headers e payload completos
  • Status de processamento
  • Número de tentativas
  • Resultado ou mensagem de erro