Visión General de Webhooks

Qué son los Webhooks

Los webhooks permiten que NTX Pay envíe notificaciones HTTPS a tu servidor cada vez que ocurre un evento relevante — confirmación de cash-in, falla de cash-out, devolución — sin que tengas que hacer polling.

Tipos de Webhook

Al registrar un webhook vía POST /api/webhooks-config, eliges qué tipo de evento recibe esa URL:

Tipo	Recibe
`cash_in`	Resultado de cobros SPEI (confirmado, rechazado, pendiente)
`cash_out`	Resultado de envíos SPEI (liquidado, rechazado, pendiente)
`refund_in`	Devolución de un cash-in — un pago que recibiste fue devuelto al pagador
`refund_out`	Devolución de un cash-out — una transferencia que enviaste fue devuelta por la contraparte
`all`	General — una única URL que recibe todos los eventos anteriores

Cada webhook se suscribe a exactamente un tipo. Para recibir varios tipos en URLs separadas, crea un webhook por tipo — o usa all para centralizar todo en una URL y enrutar por el campo event del payload.

Payload

Todo webhook entrega el mismo formato de payload:

{
  "event": "transaction.cash_in.settled",
  "transactionId": "12345",
  "amount": 50000,
  "currency": "MXN",
  "status": "LIQUIDATED",
  "destinationClabe": "012180001234567890",
  "sourceClabe": "646180123456789012",
  "payerName": "Juan Perez",
  "reference": "1234567",
  "voucher": "CEP20260512A1B2C3",
  "occurredAt": "2026-05-12T14:31:05.000Z"
}

string

Tipo del evento: transaction.cash_in.settled, transaction.cash_in.rejected, transaction.cash_in.returned, transaction.cash_out.settled, transaction.cash_out.rejected, transaction.cash_out.returned, o las variantes .pending. Usa este campo para enrutar el procesamiento.

string

Identificador de la transacción. Correlaciónalo con el id devuelto al crear el cobro/la transferencia.

integer

Monto en centavos MXN.

string

LIQUIDATED (liquidado), REJECTED (rechazado), RETURNED (devuelto), EXPIRED (expirado sin pago) o PENDING (en procesamiento).

string

CLABEs de destino y origen de la transferencia. Pueden venir null dependiendo del flujo.

string

Nombre de quien pagó (cash-in), cuando la red lo informa. Puede venir null.

string

Referencia numérica SPEI y comprobante, cuando estén disponibles.

string

Timestamp ISO 8601 del evento.

Headers

Header	Contenido
`x-event-id`	UUID único del evento — úsalo para deduplicar
`X-NTXPay-Signature`	`sha256=<hex-hmac>` del cuerpo crudo, firmado con el `secret` del webhook
`Content-Type`	`application/json`

Valida siempre la firma antes de procesar — sin eso, cualquier persona puede falsificar notificaciones. Consulta Implementación.

Garantías de Entrega

At-least-once: puedes recibir el mismo evento más de una vez. Deduplica por x-event-id.
Retries: hasta 5 intentos con backoff exponencial (a partir de ~5s) si respondes con un status distinto de 2xx.
Timeout: 10 segundos. Responde rápido — procesa de forma asíncrona si es necesario.
Orden: los eventos pueden llegar fuera de orden en condiciones de error. Revisa occurredAt en el payload.

Prácticas Recomendadas

Responde 200 inmediatamente después de validar la firma y encolar el evento.
Deduplica por x-event-id.
Enruta por el campo event — no asumas que una URL recibe un único tipo (especialmente con all).
Maneja status explícitamente — implementa los cuatro estados (LIQUIDATED, REJECTED, RETURNED, PENDING).
HTTPS obligatorio — los webhooks solo se envían a URLs con protocolo HTTPS.

Guía

Sandbox

Webhooks

Autenticación

SPEI

Webhooks Config

Visión General de Webhooks

Qué son los Webhooks

Tipos de Webhook

Payload

Headers

Garantías de Entrega

Prácticas Recomendadas

Próximos Pasos

Configuración

Implementación

​Qué son los Webhooks

​Tipos de Webhook

​Payload

​Headers

​Garantías de Entrega

​Prácticas Recomendadas

​Próximos Pasos

Configuración

Implementación

Qué son los Webhooks

Tipos de Webhook

Payload

Headers

Garantías de Entrega

Prácticas Recomendadas

Próximos Pasos