Visión general

Rapid entrega alertas y eventos al sistema del cliente por webhook HTTPS POST. Tu aplicación expone una URL, y Rapid le envía solicitudes cada vez que hay una alerta para notificar.

El webhook es el mecanismo universal de entrega. Hoy dos productos usan el canal:

• Alerta: chargeback_alert.received: llegó una alerta nueva.
• Disputa: dispute.fraud.revoke_access: llegó una disputa por fraude y la red de la tarjeta exige cortar el acceso del titular.

La URL es una sola; el campo event (y el header X-Webhook-Event) dice qué evento llegó. Cualquier producto futuro usa el mismo canal.

Internamente, los proveedores se identifican por slugs en payloads y respuestas: ethoca_alerts (Mastercard) y verifi_rdr (Visa).

Flujo resumido

1. Registras la URL de tu endpoint en el panel de Rapid; Rapid genera la clave de firma y la muestra una sola vez
2. Cuando se recibe una alerta y se asocia a tu empresa, Rapid pone la entrega en cola
3. Rapid hace un HTTP POST a tu URL con el payload del evento
4. Tu aplicación valida la firma del header X-Webhook-Signature, procesa el evento y devuelve 200 o 204
5. Si tu aplicación devuelve un error o no responde, Rapid lo intenta de nuevo (ver Reintentos y logs)

Configuración

• Cada empresa puede tener un webhook activo a la vez.
• La clave de firma (secret) la genera Rapid en el registro, se muestra una sola vez y se usa para validar la firma HMAC-SHA256. ¿La perdiste? Genera otra en Configuración › API (la anterior deja de valer al instante).
• Si el webhook está inactivo, los eventos se siguen guardando y se ven en el panel, pero no se entregan. Una revocación de acceso no entregada aparece como pendiente en la disputa, para tratamiento manual.

Próximos pasos

• Payload: estructura completa del body enviado.
• Autenticación: cómo validar X-Webhook-Signature.
• Reintentos y logs: política de reintentos.
• Buenas prácticas: idempotencia, timeout, respuesta rápida.