Webhooks de Pagos

Recibe notificaciones instantáneas cuando los pagos se crean, detectan, confirman o encuentran problemas. Los webhooks son la forma recomendada de rastrear el estado de los pagos.

Tipos de Evento

Eventos del Ciclo de Vida del Pago

Evento	Cuándo Se Dispara	Campos Clave
`PAYMENT_CREATED`	Solicitud de pago creada	amount, currency, paymentId
`PAYMENT_ADDRESS_ASSIGNED`	Dirección crypto asignada	address, coinSymbol, chainId
`PAYMENT_DETECTED`	Transacción vista en blockchain	txHash, amount, confirmations: 0
`PAYMENT_CONFIRMATION_UPDATE`	Cambio en conteo de confirmaciones	confirmations, required
`PAYMENT_CONFIRMED`	Confirmaciones requeridas alcanzadas	txHash, confirmations
`PAYMENT_SETTLED`	Pago completamente procesado	settledAmount, feeAmount
`PAYMENT_EXPIRED`	TTL expiró sin pago	expiredAt
`PAYMENT_CANCELLED`	Cancelado manualmente	cancelledBy, reason
`PAYMENT_ABANDONED`	Usuario cerró el checkout	abandonedAt

Eventos de Excepción

Event	When Fired	Key Fields
`PAYMENT_EXPIRED_PARTIAL`	Pago parcial recibido antes de expirar	expected, received
`PAYMENT_LATE_DETECTED`	Pago llegó después de expirar	txHash, delay
`PAYMENT_REORG`	Transacción invalidada por reorg de cadena	txHash (raro pero crítico)

Payload del Webhook

Todos los webhooks incluyen estos campos comunes:

Field	Description
`eventId`	Identificador único para idempotencia (evt_timestamp_hash)
`eventType`	Tipo de evento (ej. PAYMENT_CONFIRMED)
`timestamp`	Timestamp ISO-8601 de emisión del evento
`paymentRequestId`	El ID del pago en SanPay
`externalId`	Tu referencia de pedido (pasada durante la creación)
`metadata`	Datos personalizados que incluiste en la creación del pago

{
  "eventId": "evt_1704556800000_abc123",
  "eventType": "PAYMENT_CONFIRMED",
  "timestamp": "2026-01-10T15:30:00.000Z",
  "tenantId": "tenant-uuid",
  "paymentRequestId": "pr_abc123",
  "externalId": "ORDER-12345",
  "metadata": { "orderId": "ORD-12345", "customerId": "C-789" },
  "txHash": "0xabc123def456...",
  "confirmations": 12
}

Headers de Solicitud

Header	Example Value
`Content-Type`	`application/json`
`X-Event-ID`	`evt_1704556800000_abc123`
`X-Event-Type`	`PAYMENT_CONFIRMED`
`X-Webhook-Signature`	`t=timestamp,v1=signature`
`User-Agent`	`SanPay-Webhook/1.0`

Política de Reintentos

Reintentamos entregas de webhook fallidas con backoff exponencial:

Intento	Retraso
1	Inmediato
2	1 minuto
3	5 minutos
4	30 minutos
5	2 horas
6	24 horas

Mejores Prácticas

Responde Rápido

Responde 200 OK inmediatamente. Procesa lógica pesada de forma asíncrona para evitar timeouts.

Maneja Duplicados

Usa eventId para idempotencia. El mismo evento puede llegar múltiples veces debido a reintentos.

Verifica Firmas

Siempre verifica el header X-Webhook-Signature antes de confiar en el payload.

Registra Todo

Guarda payloads raw para depuración. Podrías necesitarlos para reconciliación.

Maneja Fuera de Orden

Los eventos pueden llegar fuera de secuencia. Usa timestamps y máquinas de estado.