Skip to main content

Principios

Toda implementación de webhook debe cubrir 3 cosas:
  1. Validación HMAC con el secret recibido al crear el webhook
  2. Respuesta rápida (200 OK en ≤10s)
  3. Idempotencia vía header x-event-id

Ejemplos de Código

¿Por qué raw body?

El HMAC se calcula sobre los bytes exactos que NTX Pay envió. Si el framework parsea el JSON antes (reacomodando espacios, reordenando campos), la firma no coincide. Captura siempre el body crudo en bytes antes de hacer el parse.

Enrutar por Evento y Status

El campo event identifica el flujo (transaction.cash_in.* / transaction.cash_out.*) y el status el resultado. Filtra antes de procesar:

Reintentos

Si devuelves un status ≠ 2xx (o excedes el timeout de 10s), NTX Pay reintenta hasta 5 veces con backoff exponencial a partir de ~5 segundos. Después de eso, la entrega se marca como fallida — el reenvío manual puede solicitarse a soporte.
No uses 429 para señalar el rate-limit de tu propio servicio — eso activa el retry y amplifica la carga. Responde 503 Service Unavailable si realmente no puedes procesar.

Buenas Prácticas

  • Usa Redis/base de datos para el dedupe con TTL ≥ 24h (no memoria in-process)
  • Procesa de forma asíncrona: el webhook handler solo valida + encola
  • Monitorea la latencia del handler — objetivo P95 < 500ms
  • Registra x-event-id en los logs para auditoría