# Buenas prácticas

> Lo que un endpoint de webhook necesita hacer: validar la firma, responder rápido, ser idempotente, usar HTTPS y una dirección pública.

Página: https://doc.rapidchargeback.com/es/canais/webhook/boas-praticas/

## 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](https://doc.rapidchargeback.com/es/canais/webhook/autenticacao/).

## 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)