Visión General
La configuración de webhooks se hace vía cuatro endpoints:GET /api/webhooks-config— listar webhooks activosPOST /api/webhooks-config— crear/configurar un webhookPOST /api/webhooks-config/test— disparar un webhook de prueba firmadoDELETE /api/webhooks-config/{id}— eliminar un webhook
Crear Webhook
Request
Response (201)
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 paracash_out) — enruta cada tipo a su propio endpoint/handler. - Un webhook
all— una URL única recibe todo y tu handler enruta por el campoeventdel payload.
Validar el Endpoint
Antes de liberar el webhook para recibir tráfico real:- Usa webhook.site o ngrok para inspeccionar el tráfico (el campo
overrideUrldel webhook de prueba acepta esas URLs) - Dispara entregas con
POST /api/webhooks-config/testvariando elstatus - Verifica que tu aplicación:
- Valida
X-NTXPay-Signaturecorrectamente - Devuelve
200en menos de 10 segundos - Deduplica por
x-event-id
- Valida
Próximos Pasos
Implementación
Validación HMAC en Node.js, Python, Java y Go
Eventos
Payload de cada tipo de evento