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

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

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 formato legacy vale solo para chargeback_alert.received: los demás eventos salen siempre en v2, 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)

POST https://tu-sistema.com/webhooks/rapid
Content-Type: application/json
X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp: 1790000000
X-Webhook-Event: chargeback_alert.received
X-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_id en chargeback_alert.received, dispute_id en dispute.fraud.revoke_access. Permite deduplicar sin parsear el body.

Los headers clientid/clientkey no se envían en el formato v2: lo que autentica la entrega es la firma. Siguen enviándose solo en el formato legacy (ver Formato legacy).

---

Evento chargeback_alert.received

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 inicial de la alerta. Siempre pending al recibirla	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	object | null	Datos del merchant asociado (ver abajo); null si la alerta todavía no se asoció	Sí

Objeto merchant

Campo	Tipo	Descripción
id	string (UUID)	ID del merchant en Rapid
name	string	Nombre del merchant

---

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": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Minha Loja"
  }
}

---

Evento dispute.fraud.revoke_access

Se dispara cuando Rapid recibe una disputa 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

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í
merchant	object | null	Tienda asociada (id, name); null si la disputa todavía no se asoció	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

{
  "event": "dispute.fraud.revoke_access",
  "dispute_id": "00000000-0000-0000-0000-0000000000d1",
  "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)

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í.

---

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

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

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 ni expires_at en este formato. Reintentos, timeout y logs son los mismos que en v2.