Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Rapid sends an HTTP POST with Content-Type: application/json to the configured URL. The body is a JSON object and the event field (also in the X-Webhook-Event header) says what happened.

EventProductWhen it firesBody
chargeback_alert.receivedAlertAn alert was received and matched to your companyAlert received
dispute.fraud.revoke_accessDisputeA fraud dispute arrived (Visa 10.4 / Mastercard 4837) and the card network requires you to cut off the cardholder’s accessAccess revocation
webhook.testTestSomeone on your team clicked Send test event under Settings › WebhookTest event

The same URL receives every event: use event (or the header) to route. If you only handle one of them, respond 200 to the others even without processing them.

There are two formats, set by Rapid on your account:

  • v2: the default for new accounts. Described on this page (headers, signature, body).
  • legacy: accounts migrated from the previous system. Same body and headers as the old system, without a signature. Described in the Legacy format section at the end of the page. The legacy format applies only to chargeback_alert.received: the other events always go out in v2, even on those accounts.

To find out or change your account’s format, contact Rapid support.

POST https://your-system.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 of ${X-Webhook-Timestamp}.${body} with your signing key. See Authentication.
  • X-Webhook-Timestamp: when Rapid signed, in seconds since the epoch. It is part of the signature (anti-replay) and must be checked against a 5-minute tolerance window.
  • X-Webhook-Event: the event type (see Events). Use it for routing.
  • X-Webhook-Reference-Id: the event’s reference ID: alert_id in chargeback_alert.received, dispute_id in dispute.fraud.revoke_access, test_id in webhook.test. Allows deduplication without parsing the body.

The clientid/clientkey headers are not sent in the v2 format: the signature is what authenticates the delivery. They are still sent only in the legacy format (see Legacy format).


FieldTypeDescriptionRequired
eventstringchargeback_alert.receivedYes
alert_idstring (UUID)Unique ID of the alert at Rapid; use it to call the search and status update endpointsYes
provider_alert_idstringID of the alert in the provider’s system. Useful for cross-reference when dealing directly with the provider’s supportYes
providerstringSource of the alert: ethoca_alerts or verifi_rdrYes
amountnumber | nullAmount of the disputed transaction (can be null when the provider does not send it)Yes
currencystringISO 4217 code with 3 uppercase lettersYes
card_last4stringLast 4 digits of the cardYes
card_binstringCard BIN (6-8 digits)Yes
transaction_datestringDate of the original transaction (ISO 8601, "2026-04-01T00:00:00.000Z")Yes
descriptorstringName shown on the cardholder’s statementYes
arnstringAcquirer Reference NumberNo
caidstringCard Acceptor IDNo
auth_codestringAuthorization code of the transactionNo
alert_typestringAlert type (e.g. fraud, dispute)No
reason_codestringDispute reason codeNo
issuerstringCard issuing bankNo
installment_numbernumber | nullCurrent installmentNo
installment_countnumber | nullTotal number of installmentsNo
statusstringStatus of the alert when the delivery was built. When a new alert arrives, pending. On a redelivery, or for an alert that arrived without your company identified and was matched later, it carries the status at that moment (for example expired or account_suspended). See Order and statusYes
received_atstringWhen Rapid received the alert (ISO 8601)Yes
expires_atstring | nullResponse deadline (ISO 8601), only for EthocaNo
merchant_enrollment_idstring (UUID) | nullThe enrollment that matched the alert; null when the alert was matched without an enrollmentYes
merchantobject | nullData of the matched merchant (see below); null if the alert has not been matched yetYes
FieldTypeDescription
idstring (UUID)Merchant ID at Rapid
namestringMerchant name
merchant_refstring | nullThe merchant’s reference in your system (see Create or update merchant); null when the merchant has none

merchant_enrollment_id and merchant.merchant_ref exist only in the v2 format: the legacy format does not change. If the reference is saved after the alert’s delivery started, the retries of that delivery still carry null: the alerts query brings the current value.


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

Fired when Rapid receives a fraud dispute and identifies the store that made the sale. If the dispute arrives without an identified store, the event is sent as soon as it is matched. It is also sent when the fraud dispute was prevented before it became a chargeback: in that case dispute_status comes as prevented and there is no defense to make, but the access revocation still applies. For a fraud inquiry (the bank only asked for information, with no chargeback yet) the event is not sent: it is sent if the inquiry becomes a fraud chargeback.

The card networks require the merchant to attempt to revoke the goods or services provided to the cardholder and to have a process to prevent reoccurrence (Visa Core Rules §10.4.4.3). The faster the cut-off, the smaller the loss: handle this event automatically if possible.

The merchant field says which of your stores made the sale: delivery always goes to the company’s single webhook, and you route internally.

FieldTypeDescriptionRequired
eventstringdispute.fraud.revoke_accessYes
dispute_idstring (UUID)ID of the dispute at Rapid. Use it as the idempotency key; the dispute shows up in the dashboard, under DisputesYes
dispute_statusstringState of the dispute when the event was built: received, submitted, won, lost, accepted or prevented. prevented means the dispute was prevented before it became a chargeback and there is no defense to makeYes
merchantobjectStore that made the sale (id, name)Yes
networkstringCard network: visa, mastercard, …Yes
conditionstring | nullCard network condition or reason (e.g. 10.4, 4837)No
transaction_idstring | nullID of the transaction on the network, when sent by the acquirerNo
customer_refstring | nullCustomer identifier you sent in the transaction (account_id), when there is oneNo
order_refstringOrder reference: order number, your external ID or, if neither exists, the dispute_idYes
reasonstringAlways fraud_dispute_receivedYes
is_account_takeoverbooleantrue when there are signs of account takeover (device and IP differ from the customer’s history)Yes
required_actionsstring[]Required actions: revoke_access, prevent_reoccurrence and, on account takeover, re_authenticateYes
citationobjectThe rule behind the requirement (section, visa_id, page, quote_en, ruleset_version)Yes
emitted_atstringWhen Rapid emitted the event (ISO 8601)Yes
deadline_hintstringDispute response deadline (ISO 8601) or as_soon_as_possible when no deadline is knownYes
{
"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"
}

Responding 200 already closes the delivery. If you want to record what was done, return a JSON body with the fields below. It shows up in the dashboard, on the dispute, as confirmation from your integration. An unknown key invalidates the whole body (the delivery is still valid, it just does not record the confirmation).

FieldTypeDescription
statusstringdone, partial, refused, not_applicable or accepted
actions_takenstring[]Which of the required_actions you carried out
revoked_atstringWhen access was cut off (ISO 8601)
notestringFree-text note, up to 500 characters
{
"status": "done",
"actions_taken": ["revoke_access", "prevent_reoccurrence"],
"revoked_at": "2026-09-30T14:25:03Z",
"note": "account suspended and card blocked for new purchases"
}

Idempotency: Rapid emits one event per dispute (dispute_id is unique). Retries repeat the same dispute_id, so handle it by the key instead of counting calls. If we cannot deliver it, the dispute shows up in the dashboard with the revocation pending, and the customer confirms it manually there.


Sent when someone on your team clicks Send test event under Settings › Webhook. It lets you check the endpoint before the first alert: it reaches the registered URL with the same headers and the same signature as real deliveries, the dashboard shows right away the code your URL responded with, and the attempt stays in the Delivery history.

It is not an alert: it creates nothing at Rapid, generates no charge and carries no card data. Handle it by event and respond 2xx. If your integration only processes chargeback_alert.received, responding 200 without processing is enough.

FieldTypeDescriptionRequired
eventstringwebhook.testYes
testbooleanAlways trueYes
test_idstring (UUID)ID of this test: the same value as the X-Webhook-Reference-Id header, different on every sendYes
emitted_atstringWhen Rapid sent the test (ISO 8601)Yes
{
"event": "webhook.test",
"test": true,
"test_id": "0193f0c2-7a4e-7b1d-9c3e-5f2a8d6b4e10",
"emitted_at": "2026-11-03T14:00:00.000Z"
}

The test is sent once, with no retry, with the same 30-second timeout, and it works with the webhook active or inactive. Accounts on the legacy format do not receive the test event: in that format the body does not say the event type, and the test would be read as an alert.


Your application must return one of the following codes to confirm receipt:

CodeMeaning
2xxSuccess. 200, 201, 202 and 204 are all equivalent; the body is optional

Any other code (including 4xx and 5xx) is treated as a failure and triggers a retry. Register the final URL: a 301, 302 or 303 on your URL counts as a failure (see Redirects). See Retries and logs.

In dispute.fraud.revoke_access, the body of the 200 can carry the confirmation of what you did (see above). For the other events the body is ignored.


New fields may be added to the payload in the future. Your application must ignore unknown fields instead of failing. Never change or remove fields while processing; only read them.


Accounts migrated from the previous system receive the same POST as before. Headers: Content-Type: application/json, x-source: rapid, clientid, clientkey, and no X-Webhook-Signature, X-Webhook-Event or X-Webhook-Reference-Id.

FieldTypeDescription
alert_idstringID of the alert at the provider (not Rapid’s UUID). It is the value to use in POST /chargeback-alert/get and in the POST /chargeback-alert/update/status alias
merchantstringMerchant name
providerstringethoca or verifi-rdr
descriptorstringName on the cardholder’s statement
transaction_datestringTransaction date (ISO 8601)
currencystringISO 4217
amountnumber | nullTransaction amount
card_numberstring | nullBIN******LAST4, or null when the provider sent neither BIN nor last digits
created_atstringWhen Rapid received the alert
arnstring | nullAcquirer Reference Number
authorization_codestring | nullAuthorization code
issuerstring | nullIssuing bank
typestring | nullAlert type
globalbooleantrue for an international alert
reason_code, status_code, mcc, tier, caidstring | nullProvider fields, when present
installment_number, total_installment_countnumber | nullInstallments

There is no event, status, expires_at, merchant_ref or merchant_enrollment_id field in this format. Retries, timeout and logs are the same as in v2.