Buenas prácticas

Valida la firma antes que nada

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.

Responde rápido

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.

Idempotencia

Rapid puede volver a enviar la misma alerta:

• 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

Tu procesamiento debe ser idempotente por alert_id:

1. Al recibir un webhook, verifica si ya existe un registro con ese alert_id 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

Ignora los campos desconocidos

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

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.

Usa siempre HTTPS

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.

Usa una dirección pública de internet

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.

Protege el secret

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

Monitoreo

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)