Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

Calcula y verifica X-Webhook-Signature antes de parsear el JSON o tocar la base de datos. Toda solicitud con firma inválida debe descartarse. Ver Autenticación.

Devuelve 200 o 204 lo antes posible, idealmente en menos de 1 segundo. Si necesitas procesar la alerta (ej.: actualizar la base, llamar a la API del gateway), hazlo de forma asíncrona después de responder.

El timeout es de 30 segundos por intento. Cualquier demora consume ese margen y puede disparar un reintento innecesario.

Rapid puede entregar el mismo evento más de una vez:

  • Cuando el intento anterior falló (reintento automático)
  • Cuando alguien de tu equipo reenvía la entrega desde el panel
  • En casos raros de falla de red entre la respuesta de tu servidor y la confirmación del lado de Rapid

No cuentes entregas: tu procesamiento debe ser idempotente por la referencia del evento, el header X-Webhook-Reference-Id (el alert_id en la alerta, el dispute_id en la revocación de acceso):

  1. Al recibir un webhook, verifica si ya existe un registro con esa referencia en tu sistema
  2. Si existe, devuelve 200 de inmediato y no lo proceses de nuevo
  3. Si no existe, procésalo y guárdalo

En el formato legacy ese header no existe: usa el alert_id del cuerpo.

Las entregas pueden llegar fuera de orden. Rapid entrega varios eventos al mismo tiempo, y un reintento llega después de eventos más nuevos. No deduzcas el orden por la llegada: para ordenar alertas, usa el received_at del cuerpo.

Cada entrega lleva el estado de la alerta en el momento en que se armó, y los reintentos repiten el mismo cuerpo. La alerta nueva llega pending, pero un reenvío puede traer una alerta que ya venció o ya fue respondida. Antes de actuar sobre una alerta, revisa el status y el expires_at y, si tienes dudas, consulta la alerta para ver el estado actual.

El payload puede evolucionar con campos nuevos. Tu deserialización debe tolerar campos extra en lugar de fallar. Nunca elimines ni modifiques campos al procesar.

Devuelve 200 incluso con error de validación

Sección titulada «Devuelve 200 incluso con error de validación»

Si el payload llega pero no puedes procesarlo (ej.: el merchant no existe de tu lado), igual devuelve 200. Devolver un error dispara un reintento inútil.

Registra la falla de tu lado (log, alerta interna, cola de errores) y trátala offline.

La URL del webhook tiene que ser https://: el panel no permite guardar una URL http://, y Rapid no entrega por HTTP plano. La firma prueba que la solicitud vino de Rapid, pero no cifra el contenido, y el payload lleva datos de la tarjeta (BIN y últimos 4 dígitos) y de la compra.

La URL tiene que apuntar a un servidor accesible desde internet. Rapid no entrega en una dirección de red local o privada: localhost, 127.0.0.1, 10.x, 172.16.x a 172.31.x, 192.168.x y sus equivalentes en IPv6. El panel ya rechaza esas direcciones en el registro, y un nombre de dominio que resuelva a una de ellas falla en el momento de la entrega.

Para probar la integración en tu máquina, expón el servidor local con un túnel HTTPS (como ngrok o Cloudflare Tunnel) y registra la dirección pública que genera. Para revisar el endpoint antes de la primera alerta, usa Enviar evento de prueba, en Configuración › Webhook (ver Evento de prueba).

El secret usado para validar X-Webhook-Signature debe tratarse como una credencial sensible:

  • No lo subas a un repositorio
  • No lo registres en logs
  • Guárdalo en una variable de entorno o en un gestor de secretos

Recomendamos instrumentar:

  • Tasa de webhooks recibidos (si cae, algo puede estar mal en Rapid o en la red)
  • Tasa de firmas inválidas (si sube, puede indicar una rotación de secret no propagada o un intento de falsificación)
  • Latencia de procesamiento (para asegurar que quede por debajo del timeout de 30 s)
  • Tasa de reintentos entregados (indica problemas de tu lado)