Payload
Rapid envía un HTTP POST con Content-Type: application/json a la URL configurada. El cuerpo es un objeto JSON y el campo event (también en el header X-Webhook-Event) dice qué pasó.
Eventos
Sección titulada «Eventos»| Evento | Producto | Cuándo se dispara | Cuerpo |
|---|---|---|---|
chargeback_alert.received | Alerta | Se recibió una alerta y se asoció a tu empresa | Alerta recibida |
dispute.fraud.revoke_access | Disputa | Llegó una disputa por fraude (Visa 10.4 / Mastercard 4837) y la red de la tarjeta exige que cortes el acceso del titular | Revocación de acceso |
webhook.test | Prueba | Alguien de tu equipo hizo clic en Enviar evento de prueba, en Configuración › Webhook | Evento de prueba |
La misma URL recibe todos los eventos: usa event (o el header) para enrutar. Si solo tratas uno de ellos, responde 200 a los demás aunque no los proceses.
Hay dos formatos, definidos por Rapid en tu cuenta:
v2: el predeterminado para cuentas nuevas. Descrito en esta página (headers, firma, cuerpo).legacy: cuentas migradas del sistema anterior. Mismo cuerpo y headers que el sistema antiguo, sin firma. Descrito en la sección Formato legacy al final de la página. El formatolegacyvale solo parachargeback_alert.received: los demás eventos salen siempre env2, incluso en esas cuentas.
Para saber o cambiar el formato de tu cuenta, habla con el soporte de Rapid.
Método y headers (formato v2)
Sección titulada «Método y headers (formato v2)»POST https://tu-sistema.com/webhooks/rapidContent-Type: application/jsonX-Webhook-Signature: sha256=<hmac_hex>X-Webhook-Timestamp: 1790000000X-Webhook-Event: chargeback_alert.receivedX-Webhook-Reference-Id: <alert_id>X-Webhook-Signature: HMAC-SHA256 de${X-Webhook-Timestamp}.${body}con tu clave de firma. Ver Autenticación.X-Webhook-Timestamp: cuándo firmó Rapid, en segundos desde la epoch. Forma parte de la firma (anti-replay) y debe verificarse contra una ventana de tolerancia de 5 minutos.X-Webhook-Event: tipo del evento (ver Eventos). Úsalo para enrutar.X-Webhook-Reference-Id: ID de referencia del evento:alert_idenchargeback_alert.received,dispute_idendispute.fraud.revoke_access,test_idenwebhook.test. Permite deduplicar sin parsear el body.
Los headers
clientid/clientkeyno se envían en el formatov2: lo que autentica la entrega es la firma. Siguen enviándose solo en el formatolegacy(ver Formato legacy).
Evento chargeback_alert.received
Sección titulada «Evento chargeback_alert.received»Estructura del cuerpo
Sección titulada «Estructura del cuerpo»| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
event | string | chargeback_alert.received | Sí |
alert_id | string (UUID) | ID único de la alerta en Rapid; úsalo para llamar a los endpoints de consulta y actualización de estado | Sí |
provider_alert_id | string | ID de la alerta en el sistema del proveedor. Útil como referencia cruzada si tratas directamente con el soporte del proveedor | Sí |
provider | string | Origen de la alerta: ethoca_alerts o verifi_rdr | Sí |
amount | number | null | Monto de la transacción disputada (puede venir null cuando el proveedor no lo informa) | Sí |
currency | string | Código ISO 4217 con 3 letras mayúsculas | Sí |
card_last4 | string | Últimos 4 dígitos de la tarjeta | Sí |
card_bin | string | BIN de la tarjeta (6-8 dígitos) | Sí |
transaction_date | string | Fecha de la transacción original (ISO 8601, "2026-04-01T00:00:00.000Z") | Sí |
descriptor | string | Nombre que aparece en el resumen del titular | Sí |
arn | string | Acquirer Reference Number | No |
caid | string | Card Acceptor ID | No |
auth_code | string | Código de autorización de la transacción | No |
alert_type | string | Tipo de alerta (ej.: fraud, dispute) | No |
reason_code | string | Código del motivo de la disputa | No |
issuer | string | Banco emisor de la tarjeta | No |
installment_number | number | null | Cuota actual | No |
installment_count | number | null | Total de cuotas | No |
status | string | Estado de la alerta cuando se armó la entrega. Al llegar una alerta nueva, pending. En un reenvío, o en una alerta que llegó sin tu empresa identificada y se asoció después, trae el estado de ese momento (por ejemplo expired o account_suspended). Ver Orden y estado | Sí |
received_at | string | Cuándo Rapid recibió la alerta (ISO 8601) | Sí |
expires_at | string | null | Plazo de respuesta (ISO 8601), solo para Ethoca | No |
merchant_enrollment_id | string (UUID) | null | El enrollment que coincidió con la alerta; null cuando la alerta se asoció sin enrollment | Sí |
merchant | object | null | Datos del merchant asociado (ver abajo); null si la alerta todavía no se asoció | Sí |
Objeto merchant
Sección titulada «Objeto merchant»| Campo | Tipo | Descripción |
|---|---|---|
id | string (UUID) | ID del merchant en Rapid |
name | string | Nombre del merchant |
merchant_ref | string | null | La referencia del merchant en tu sistema (ver Crear o actualizar merchant); null cuando el merchant no tiene |
merchant_enrollment_id y merchant.merchant_ref solo existen en el formato v2: el formato legacy no cambia. Si la referencia se guarda después de que empezó la entrega de la alerta, los reintentos de esa entrega todavía llevan null: la consulta de alertas trae el valor actual.
Ejemplo de payload
Sección titulada «Ejemplo de payload»{ "event": "chargeback_alert.received", "alert_id": "00000000-0000-0000-0000-000000000099", "provider_alert_id": "2UBOD4MKAI42RPXEYU4UVQPS", "provider": "ethoca_alerts", "amount": 150.00, "currency": "USD", "card_last4": "4242", "card_bin": "424242", "transaction_date": "2026-04-01T00:00:00.000Z", "descriptor": "LOJA EXEMPLO", "arn": "74537119547024600128228", "caid": "123456789", "auth_code": "123456", "alert_type": "fraud", "reason_code": "4853", "issuer": "Chase Bank", "installment_number": null, "installment_count": null, "status": "pending", "received_at": "2026-04-14T10:00:00Z", "expires_at": "2026-04-15T10:00:00Z", "merchant_enrollment_id": "00000000-0000-0000-0000-0000000000aa", "merchant": { "id": "00000000-0000-0000-0000-000000000001", "name": "Minha Loja", "merchant_ref": "PB-1001" }}Evento dispute.fraud.revoke_access
Sección titulada «Evento dispute.fraud.revoke_access»Se dispara cuando Rapid recibe una disputa por fraude e identifica la tienda que hizo la venta. Si la disputa llega sin la tienda identificada, el evento sale en cuanto se asocia. También sale cuando la disputa por fraude se evitó antes de convertirse en contracargo: en ese caso dispute_status viene prevented y no hay defensa que hacer, pero el corte de acceso vale igual. En una consulta por fraude (el banco solo pidió información, todavía sin contracargo) el evento no sale: sale si la consulta se convierte en contracargo por fraude.
Las redes de tarjetas exigen que el comercio intente revocar el producto o servicio entregado al titular y tenga un proceso para evitar la reincidencia (Visa Core Rules §10.4.4.3). Cuanto más rápido el corte, menor la pérdida: trata este evento de forma automática si es posible.
El campo merchant dice cuál de tus tiendas hizo la venta: la entrega siempre va al webhook único de la empresa, y tú enrutas internamente.
Estructura del cuerpo
Sección titulada «Estructura del cuerpo»| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
event | string | dispute.fraud.revoke_access | Sí |
dispute_id | string (UUID) | ID de la disputa en Rapid. Úsalo como clave de idempotencia; la disputa aparece en el panel, en Disputas | Sí |
dispute_status | string | Situación de la disputa cuando se armó el evento: received, submitted, won, lost, accepted o prevented. prevented quiere decir que la disputa se evitó antes de convertirse en contracargo y no hay defensa que hacer | Sí |
merchant | object | Tienda que hizo la venta (id, name) | Sí |
network | string | Red de la tarjeta: visa, mastercard, … | Sí |
condition | string | null | Condición o motivo de la red (ej.: 10.4, 4837) | No |
transaction_id | string | null | ID de la transacción en la red, cuando lo informa el adquirente | No |
customer_ref | string | null | Identificador del cliente que enviaste en la transacción (account_id), cuando existe | No |
order_ref | string | Referencia del pedido: número de pedido, tu ID externo o, si no hay ninguno, el dispute_id | Sí |
reason | string | Siempre fraud_dispute_received | Sí |
is_account_takeover | boolean | true cuando hay indicios de cuenta tomada (dispositivo e IP difieren del historial del cliente) | Sí |
required_actions | string[] | Acciones exigidas: revoke_access, prevent_reoccurrence y, en cuenta tomada, re_authenticate | Sí |
citation | object | Regla que fundamenta la exigencia (section, visa_id, page, quote_en, ruleset_version) | Sí |
emitted_at | string | Cuándo Rapid emitió el evento (ISO 8601) | Sí |
deadline_hint | string | Plazo de respuesta de la disputa (ISO 8601) o as_soon_as_possible cuando no hay plazo conocido | Sí |
Ejemplo de payload
Sección titulada «Ejemplo de payload»{ "event": "dispute.fraud.revoke_access", "dispute_id": "00000000-0000-0000-0000-0000000000d1", "dispute_status": "received", "merchant": { "id": "00000000-0000-0000-0000-000000000001", "name": "Minha Loja" }, "network": "visa", "condition": "10.4", "transaction_id": "ch_3Qx0000000", "customer_ref": "acct-8842", "order_ref": "PED-5078", "reason": "fraud_dispute_received", "is_account_takeover": false, "required_actions": ["revoke_access", "prevent_reoccurrence"], "citation": { "section": "10.4.4.3", "visa_id": "0030642", "page": 634, "quote_en": "An Acquirer must ensure that its Merchant attempts to revoke provision of goods or services from the Cardholder after a Dispute category 10 (Fraud) Dispute and that the Merchant has a process in place to prevent reoccurrence by the Cardholder.", "ruleset_version": "visa-core-rules-2026-04-18" }, "emitted_at": "2026-09-30T14:25:00.000Z", "deadline_hint": "2026-10-14T14:20:00.000Z"}Confirmar lo que hiciste (opcional)
Sección titulada «Confirmar lo que hiciste (opcional)»Responder 200 ya cierra la entrega. Si quieres registrar lo que se hizo, devuelve en el cuerpo un JSON con los campos de abajo. Aparece en el panel, en la disputa, como confirmación de tu integración. Una clave desconocida invalida todo el cuerpo (la entrega sigue siendo válida, solo no registra la confirmación).
| Campo | Tipo | Descripción |
|---|---|---|
status | string | done, partial, refused, not_applicable o accepted |
actions_taken | string[] | Cuáles de las required_actions ejecutaste |
revoked_at | string | Cuándo se cortó el acceso (ISO 8601) |
note | string | Observación libre, hasta 500 caracteres |
{ "status": "done", "actions_taken": ["revoke_access", "prevent_reoccurrence"], "revoked_at": "2026-09-30T14:25:03Z", "note": "cuenta suspendida y tarjeta bloqueada para nuevas compras"}Idempotencia: Rapid emite un evento por disputa (dispute_id es único). Los reintentos repiten el mismo dispute_id, así que trátalo por la clave en lugar de contar llamadas. Si no logramos entregarlo, la disputa aparece en el panel con la revocación pendiente, y el cliente la confirma manualmente ahí.
Evento webhook.test
Sección titulada «Evento webhook.test»Sale cuando alguien de tu equipo hace clic en Enviar evento de prueba, en Configuración › Webhook. Sirve para revisar el endpoint antes de la primera alerta: llega a la URL registrada con los mismos headers y la misma firma de las entregas reales, el panel muestra en el momento el código que respondió tu URL, y el intento queda en el Historial de entregas.
No es una alerta: no crea nada en Rapid, no genera cobro y no trae datos de tarjeta. Trátalo por el event y responde 2xx. Si tu integración solo procesa chargeback_alert.received, basta con responder 200 sin procesarlo.
Estructura del cuerpo
Sección titulada «Estructura del cuerpo»| Campo | Tipo | Descripción | Obligatorio |
|---|---|---|---|
event | string | webhook.test | Sí |
test | boolean | Siempre true | Sí |
test_id | string (UUID) | ID de esta prueba: el mismo valor del header X-Webhook-Reference-Id, distinto en cada envío | Sí |
emitted_at | string | Cuándo Rapid envió la prueba (ISO 8601) | Sí |
Ejemplo de payload
Sección titulada «Ejemplo de payload»{ "event": "webhook.test", "test": true, "test_id": "0193f0c2-7a4e-7b1d-9c3e-5f2a8d6b4e10", "emitted_at": "2026-11-03T14:00:00.000Z"}La prueba sale una vez, sin reintento, con el mismo timeout de 30 segundos, y vale con el webhook activo o desactivado. Las cuentas en formato legacy no reciben el evento de prueba: en ese formato el cuerpo no dice el tipo de evento, y la prueba se leería como alerta.
Respuesta esperada
Sección titulada «Respuesta esperada»Tu aplicación debe devolver uno de los siguientes códigos para confirmar la recepción:
| Código | Significado |
|---|---|
2xx | Éxito. 200, 201, 202 y 204 valen lo mismo; el cuerpo es opcional |
Cualquier otro código (incluidos 4xx y 5xx) se trata como falla y dispara un reintento. Registra la URL final: un 301, 302 o 303 en tu URL cuenta como falla (ver Redirección). Ver Reintentos y logs.
En dispute.fraud.revoke_access, el cuerpo del 200 puede traer la confirmación de lo que ejecutaste (ver arriba). En los demás eventos el cuerpo se ignora.
Campos que pueden evolucionar
Sección titulada «Campos que pueden evolucionar»Se pueden agregar campos nuevos al payload en el futuro. Tu aplicación debe ignorar los campos desconocidos en lugar de fallar. Nunca modifiques ni elimines campos al procesar; solo léelos.
Formato legacy
Sección titulada «Formato legacy»Las cuentas migradas del sistema anterior reciben el mismo POST de antes. Headers: Content-Type: application/json, x-source: rapid, clientid, clientkey, y sin X-Webhook-Signature, X-Webhook-Event ni X-Webhook-Reference-Id.
| Campo | Tipo | Descripción |
|---|---|---|
alert_id | string | ID de la alerta en el proveedor (no es el UUID de Rapid). Es el valor a usar en POST /chargeback-alert/get y en el alias POST /chargeback-alert/update/status |
merchant | string | Nombre del merchant |
provider | string | ethoca o verifi-rdr |
descriptor | string | Nombre en el resumen del titular |
transaction_date | string | Fecha de la transacción (ISO 8601) |
currency | string | ISO 4217 |
amount | number | null | Monto de la transacción |
card_number | string | null | BIN******LAST4, o null cuando el proveedor no informó BIN ni últimos dígitos |
created_at | string | Cuándo Rapid recibió la alerta |
arn | string | null | Acquirer Reference Number |
authorization_code | string | null | Código de autorización |
issuer | string | null | Banco emisor |
type | string | null | Tipo de alerta |
global | boolean | true para alerta internacional |
reason_code, status_code, mcc, tier, caid | string | null | Campos del proveedor, cuando existen |
installment_number, total_installment_count | number | null | Cuotas |
No hay campo event, status, expires_at, merchant_ref ni merchant_enrollment_id en este formato. Reintentos, timeout y logs son los mismos que en v2.