Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

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

EventoProductoCuándo se disparaCuerpo
chargeback_alert.receivedAlertaSe recibió una alerta y se asoció a tu empresaAlerta recibida
dispute.fraud.revoke_accessDisputaLlegó una disputa por fraude (Visa 10.4 / Mastercard 4837) y la red de la tarjeta exige que cortes el acceso del titularRevocación de acceso
webhook.testPruebaAlguien de tu equipo hizo clic en Enviar evento de prueba, en Configuración › WebhookEvento 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 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.

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, test_id en webhook.test. 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).


CampoTipoDescripciónObligatorio
eventstringchargeback_alert.receivedSí
alert_idstring (UUID)ID único de la alerta en Rapid; úsalo para llamar a los endpoints de consulta y actualización de estadoSí
provider_alert_idstringID de la alerta en el sistema del proveedor. Útil como referencia cruzada si tratas directamente con el soporte del proveedorSí
providerstringOrigen de la alerta: ethoca_alerts o verifi_rdrSí
amountnumber | nullMonto de la transacción disputada (puede venir null cuando el proveedor no lo informa)Sí
currencystringCódigo ISO 4217 con 3 letras mayúsculasSí
card_last4stringÚltimos 4 dígitos de la tarjetaSí
card_binstringBIN de la tarjeta (6-8 dígitos)Sí
transaction_datestringFecha de la transacción original (ISO 8601, "2026-04-01T00:00:00.000Z")Sí
descriptorstringNombre que aparece en el resumen del titularSí
arnstringAcquirer Reference NumberNo
caidstringCard Acceptor IDNo
auth_codestringCódigo de autorización de la transacciónNo
alert_typestringTipo de alerta (ej.: fraud, dispute)No
reason_codestringCódigo del motivo de la disputaNo
issuerstringBanco emisor de la tarjetaNo
installment_numbernumber | nullCuota actualNo
installment_countnumber | nullTotal de cuotasNo
statusstringEstado 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 estadoSí
received_atstringCuándo Rapid recibió la alerta (ISO 8601)Sí
expires_atstring | nullPlazo de respuesta (ISO 8601), solo para EthocaNo
merchant_enrollment_idstring (UUID) | nullEl enrollment que coincidió con la alerta; null cuando la alerta se asoció sin enrollmentSí
merchantobject | nullDatos del merchant asociado (ver abajo); null si la alerta todavía no se asocióSí
CampoTipoDescripción
idstring (UUID)ID del merchant en Rapid
namestringNombre del merchant
merchant_refstring | nullLa 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.


{
"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"
}
}

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.

CampoTipoDescripciónObligatorio
eventstringdispute.fraud.revoke_accessSí
dispute_idstring (UUID)ID de la disputa en Rapid. Úsalo como clave de idempotencia; la disputa aparece en el panel, en DisputasSí
dispute_statusstringSituació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 hacerSí
merchantobjectTienda que hizo la venta (id, name)Sí
networkstringRed de la tarjeta: visa, mastercard, …Sí
conditionstring | nullCondición o motivo de la red (ej.: 10.4, 4837)No
transaction_idstring | nullID de la transacción en la red, cuando lo informa el adquirenteNo
customer_refstring | nullIdentificador del cliente que enviaste en la transacción (account_id), cuando existeNo
order_refstringReferencia del pedido: número de pedido, tu ID externo o, si no hay ninguno, el dispute_idSí
reasonstringSiempre fraud_dispute_receivedSí
is_account_takeoverbooleantrue cuando hay indicios de cuenta tomada (dispositivo e IP difieren del historial del cliente)Sí
required_actionsstring[]Acciones exigidas: revoke_access, prevent_reoccurrence y, en cuenta tomada, re_authenticateSí
citationobjectRegla que fundamenta la exigencia (section, visa_id, page, quote_en, ruleset_version)Sí
emitted_atstringCuándo Rapid emitió el evento (ISO 8601)Sí
deadline_hintstringPlazo de respuesta de la disputa (ISO 8601) o as_soon_as_possible cuando no hay plazo conocidoSí
{
"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"
}

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

CampoTipoDescripción
statusstringdone, partial, refused, not_applicable o accepted
actions_takenstring[]Cuáles de las required_actions ejecutaste
revoked_atstringCuándo se cortó el acceso (ISO 8601)
notestringObservació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í.


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.

CampoTipoDescripciónObligatorio
eventstringwebhook.testSí
testbooleanSiempre trueSí
test_idstring (UUID)ID de esta prueba: el mismo valor del header X-Webhook-Reference-Id, distinto en cada envíoSí
emitted_atstringCuándo Rapid envió la prueba (ISO 8601)Sí
{
"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.


Tu aplicación debe devolver uno de los siguientes códigos para confirmar la recepción:

CódigoSignificado
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.


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.


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.

CampoTipoDescripción
alert_idstringID 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
merchantstringNombre del merchant
providerstringethoca o verifi-rdr
descriptorstringNombre en el resumen del titular
transaction_datestringFecha de la transacción (ISO 8601)
currencystringISO 4217
amountnumber | nullMonto de la transacción
card_numberstring | nullBIN******LAST4, o null cuando el proveedor no informó BIN ni últimos dígitos
created_atstringCuándo Rapid recibió la alerta
arnstring | nullAcquirer Reference Number
authorization_codestring | nullCódigo de autorización
issuerstring | nullBanco emisor
typestring | nullTipo de alerta
globalbooleantrue para alerta internacional
reason_code, status_code, mcc, tier, caidstring | nullCampos del proveedor, cuando existen
installment_number, total_installment_countnumber | nullCuotas

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.