Skip to main content

Visión General

La configuración de webhooks se hace vía cuatro endpoints:
  • GET /api/webhooks-config — listar webhooks activos
  • POST /api/webhooks-config — crear/configurar un webhook
  • POST /api/webhooks-config/test — disparar un webhook de prueba firmado
  • DELETE /api/webhooks-config/{id} — eliminar un webhook

Crear Webhook

Request

Response (201)

Si omites secret en el request, NTX Pay lo genera automáticamente y lo devuelve en la respuesta — guárdalo de inmediato, no se muestra de nuevo.

Campos

string
requerido
URL HTTPS del endpoint que recibirá los webhooks. HTTP simple es rechazado.
array
requerido
Un webhook se suscribe a exactamente UN evento — el array debe contener un único elemento. Valores aceptados: cash_in, cash_out, refund_in, refund_out, all (General — recibe todos los eventos) e internal_transfer. Consulta la semántica de cada tipo en la Visión General.
string
Secret HMAC para validar la firma. Mínimo 8 caracteres, máximo 128. Si se omite, NTX Pay lo genera.

Webhook de Prueba

Después de crear el webhook, dispara una entrega de prueba firmada con el mismo secret — sin necesidad de mover una transacción:
string
requerido
Qué webhook recibe la prueba: cash_in, cash_out, refund_in, refund_out o internal_transfer.
string
Status simulado en el payload: LIQUIDATED (default), PENDING, REJECTED o RETURNED.
string
URL temporal de prueba (ej.: webhook.site). Si se omite, entrega en la URL configurada.
integer
Monto en centavos en el payload de prueba (default 1000 = $10.00 MXN).
delivered: true significa que tu endpoint respondió 2xx. statusCode: 0 indica error de conexión.

Listar Webhooks

La respuesta del listado no incluye el secret — solo se muestra en la creación.

Eliminar Webhook

Múltiples Webhooks

Cada webhook se suscribe a exactamente un evento, así que tienes dos estrategias:
  • Un webhook por tipo (ej.: uno para cash_in, otro para cash_out) — enruta cada tipo a su propio endpoint/handler.
  • Un webhook all — una URL única recibe todo y tu handler enruta por el campo event del payload.

Validar el Endpoint

Antes de liberar el webhook para recibir tráfico real:
  1. Usa webhook.site o ngrok para inspeccionar el tráfico (el campo overrideUrl del webhook de prueba acepta esas URLs)
  2. Dispara entregas con POST /api/webhooks-config/test variando el status
  3. Verifica que tu aplicación:
    • Valida X-NTXPay-Signature correctamente
    • Devuelve 200 en menos de 10 segundos
    • Deduplica por x-event-id

Próximos Pasos

Implementación

Validación HMAC en Node.js, Python, Java y Go

Eventos

Payload de cada tipo de evento