Payload
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.
Events
Section titled “Events”| Event | Product | When it fires | Body |
|---|---|---|---|
chargeback_alert.received | Alert | An alert was received and matched to your company | Alert received |
dispute.fraud.revoke_access | Dispute | A fraud dispute arrived (Visa 10.4 / Mastercard 4837) and the card network requires you to cut off the cardholder’s access | Access revocation |
webhook.test | Test | Someone on your team clicked Send test event under Settings › Webhook | Test 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. Thelegacyformat applies only tochargeback_alert.received: the other events always go out inv2, even on those accounts.
To find out or change your account’s format, contact Rapid support.
Method and headers (v2 format)
Section titled “Method and headers (v2 format)”POST https://your-system.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 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_idinchargeback_alert.received,dispute_idindispute.fraud.revoke_access,test_idinwebhook.test. Allows deduplication without parsing the body.
The
clientid/clientkeyheaders are not sent in thev2format: the signature is what authenticates the delivery. They are still sent only in thelegacyformat (see Legacy format).
chargeback_alert.received event
Section titled “chargeback_alert.received event”Body structure
Section titled “Body structure”| Field | Type | Description | Required |
|---|---|---|---|
event | string | chargeback_alert.received | Yes |
alert_id | string (UUID) | Unique ID of the alert at Rapid; use it to call the search and status update endpoints | Yes |
provider_alert_id | string | ID of the alert in the provider’s system. Useful for cross-reference when dealing directly with the provider’s support | Yes |
provider | string | Source of the alert: ethoca_alerts or verifi_rdr | Yes |
amount | number | null | Amount of the disputed transaction (can be null when the provider does not send it) | Yes |
currency | string | ISO 4217 code with 3 uppercase letters | Yes |
card_last4 | string | Last 4 digits of the card | Yes |
card_bin | string | Card BIN (6-8 digits) | Yes |
transaction_date | string | Date of the original transaction (ISO 8601, "2026-04-01T00:00:00.000Z") | Yes |
descriptor | string | Name shown on the cardholder’s statement | Yes |
arn | string | Acquirer Reference Number | No |
caid | string | Card Acceptor ID | No |
auth_code | string | Authorization code of the transaction | No |
alert_type | string | Alert type (e.g. fraud, dispute) | No |
reason_code | string | Dispute reason code | No |
issuer | string | Card issuing bank | No |
installment_number | number | null | Current installment | No |
installment_count | number | null | Total number of installments | No |
status | string | Status 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 status | Yes |
received_at | string | When Rapid received the alert (ISO 8601) | Yes |
expires_at | string | null | Response deadline (ISO 8601), only for Ethoca | No |
merchant_enrollment_id | string (UUID) | null | The enrollment that matched the alert; null when the alert was matched without an enrollment | Yes |
merchant | object | null | Data of the matched merchant (see below); null if the alert has not been matched yet | Yes |
merchant object
Section titled “merchant object”| Field | Type | Description |
|---|---|---|
id | string (UUID) | Merchant ID at Rapid |
name | string | Merchant name |
merchant_ref | string | null | The 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.
Payload example
Section titled “Payload example”{ "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" }}dispute.fraud.revoke_access event
Section titled “dispute.fraud.revoke_access event”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.
Body structure
Section titled “Body structure”| Field | Type | Description | Required |
|---|---|---|---|
event | string | dispute.fraud.revoke_access | Yes |
dispute_id | string (UUID) | ID of the dispute at Rapid. Use it as the idempotency key; the dispute shows up in the dashboard, under Disputes | Yes |
dispute_status | string | State 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 make | Yes |
merchant | object | Store that made the sale (id, name) | Yes |
network | string | Card network: visa, mastercard, … | Yes |
condition | string | null | Card network condition or reason (e.g. 10.4, 4837) | No |
transaction_id | string | null | ID of the transaction on the network, when sent by the acquirer | No |
customer_ref | string | null | Customer identifier you sent in the transaction (account_id), when there is one | No |
order_ref | string | Order reference: order number, your external ID or, if neither exists, the dispute_id | Yes |
reason | string | Always fraud_dispute_received | Yes |
is_account_takeover | boolean | true when there are signs of account takeover (device and IP differ from the customer’s history) | Yes |
required_actions | string[] | Required actions: revoke_access, prevent_reoccurrence and, on account takeover, re_authenticate | Yes |
citation | object | The rule behind the requirement (section, visa_id, page, quote_en, ruleset_version) | Yes |
emitted_at | string | When Rapid emitted the event (ISO 8601) | Yes |
deadline_hint | string | Dispute response deadline (ISO 8601) or as_soon_as_possible when no deadline is known | Yes |
Payload example
Section titled “Payload example”{ "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"}Confirming what you did (optional)
Section titled “Confirming what you did (optional)”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).
| Field | Type | Description |
|---|---|---|
status | string | done, partial, refused, not_applicable or accepted |
actions_taken | string[] | Which of the required_actions you carried out |
revoked_at | string | When access was cut off (ISO 8601) |
note | string | Free-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.
webhook.test event
Section titled “webhook.test event”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.
Body structure
Section titled “Body structure”| Field | Type | Description | Required |
|---|---|---|---|
event | string | webhook.test | Yes |
test | boolean | Always true | Yes |
test_id | string (UUID) | ID of this test: the same value as the X-Webhook-Reference-Id header, different on every send | Yes |
emitted_at | string | When Rapid sent the test (ISO 8601) | Yes |
Payload example
Section titled “Payload example”{ "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.
Expected response
Section titled “Expected response”Your application must return one of the following codes to confirm receipt:
| Code | Meaning |
|---|---|
2xx | Success. 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.
Fields that may evolve
Section titled “Fields that may evolve”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.
Legacy format
Section titled “Legacy format”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.
| Field | Type | Description |
|---|---|---|
alert_id | string | ID 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 |
merchant | string | Merchant name |
provider | string | ethoca or verifi-rdr |
descriptor | string | Name on the cardholder’s statement |
transaction_date | string | Transaction date (ISO 8601) |
currency | string | ISO 4217 |
amount | number | null | Transaction amount |
card_number | string | null | BIN******LAST4, or null when the provider sent neither BIN nor last digits |
created_at | string | When Rapid received the alert |
arn | string | null | Acquirer Reference Number |
authorization_code | string | null | Authorization code |
issuer | string | null | Issuing bank |
type | string | null | Alert type |
global | boolean | true for an international alert |
reason_code, status_code, mcc, tier, caid | string | null | Provider fields, when present |
installment_number, total_installment_count | number | null | Installments |
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.