Saltar al contenido principal

Callbacks (Webhooks de los Proveedores)

Los proveedores de gateway envían notificaciones al sistema cuando el estado de los pagos cambia. Estas notificaciones se procesan de forma asíncrona.

Endpoints de Callback​

Kobana​

POST /api/callbacks/kobana

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

Eventos recibidos:

  • 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 Firma: x-hub-signature: sha256=<hex>

Eventos recibidos:

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

Flujo de Procesamiento​

Recibe POST del proveedor
  → Valida firma HMAC-SHA256
  → Verifica clave de idempotencia (ignora duplicados)
  → Crea registro de Callback (status=pending)
  → Encola job para procesamiento asíncrono
  → Retorna 200 inmediatamente

Procesamiento Asíncrono​

Worker procesa la cola
  → Enruta al handler del proveedor
  → Mapea estado del proveedor a estado interno
  → Actualiza registro de pago
  → Crea evento para notificación
  → Actualiza Callback (status=completed)

Seguridad​

  • Validación de firma: HMAC-SHA256 con comparación timing-safe
  • Idempotencia: Clave única [provider, idempotencyKey] previene duplicación
  • Reintentos: Máximo de 5 intentos con backoff exponencial
  • Retención: Callbacks fallidos mantenidos por 7 días

Registro de Callback​

Cada callback recibido se registra con:

  • Proveedor de origen
  • Clave de idempotencia
  • Headers y payload completos
  • Estado de procesamiento
  • Número de intentos
  • Resultado o mensaje de error