Payload

A Rapid envia HTTP POST com Content-Type: application/json para a URL configurada. O corpo é um objeto JSON e o campo event (também no header X-Webhook-Event) diz o que aconteceu.

Eventos

Evento	Produto	Quando dispara	Corpo
chargeback_alert.received	Alerta	Um alerta foi recebido e associado à sua empresa	Alerta recebido
dispute.fraud.revoke_access	Disputa	Chegou uma disputa de fraude (Visa 10.4 / Mastercard 4837) e a bandeira exige que você corte o acesso do portador	Revogação de acesso

A mesma URL recebe todos os eventos: use event (ou o header) para rotear. Se você só trata um deles, responda 200 para os demais mesmo sem processar.

Existem dois formatos, definidos pela Rapid na sua conta:

• v2: padrão para contas novas. Descrito nesta página (headers, assinatura, corpo).
• legacy: contas migradas do sistema anterior. Mesmo corpo e headers do sistema antigo, sem assinatura. Descrito na seção Formato legacy no fim da página. O formato legacy vale apenas para chargeback_alert.received: os outros eventos saem sempre em v2, mesmo nessas contas.

Para saber/alterar o formato da sua conta, fale com o suporte da Rapid.

Método e headers (formato v2)

POST https://seu-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} com a sua chave de assinatura. Ver Autenticação.
• X-Webhook-Timestamp: quando a Rapid assinou, em segundos desde a epoch. Entra na assinatura (anti-replay) e deve ser conferido contra uma janela de tolerância de 5 minutos.
• X-Webhook-Event: tipo do evento (ver Eventos). Use para roteamento.
• X-Webhook-Reference-Id: ID de referência do evento: alert_id em chargeback_alert.received, dispute_id em dispute.fraud.revoke_access. Permite deduplicação sem parsear o body.

Os headers clientid/clientkey não são enviados no formato v2: quem autentica a entrega é a assinatura. Eles seguem indo apenas no formato legacy (ver Formato legacy).

---

Evento chargeback_alert.received

Estrutura do corpo

Campo	Tipo	Descrição	Obrigatório
event	string	chargeback_alert.received	Sim
alert_id	string (UUID)	ID único do alerta na Rapid, use para chamar os endpoints de consulta e atualização de status	Sim
provider_alert_id	string	ID do alerta no sistema do provedor. Útil para cross-referência em caso de suporte direto com o provedor	Sim
provider	string	Origem do alerta: ethoca_alerts ou verifi_rdr	Sim
amount	number | null	Valor da transação disputada (pode vir null quando o provedor não informa)	Sim
currency	string	Código ISO 4217 com 3 letras maiúsculas	Sim
card_last4	string	Últimos 4 dígitos do cartão	Sim
card_bin	string	BIN do cartão (6-8 dígitos)	Sim
transaction_date	string	Data da transação original (ISO 8601, "2026-04-01T00:00:00.000Z")	Sim
descriptor	string	Nome exibido na fatura do portador	Sim
arn	string	Acquirer Reference Number	Não
caid	string	Card Acceptor ID	Não
auth_code	string	Código de autorização da transação	Não
alert_type	string	Tipo do alerta (ex: fraud, dispute)	Não
reason_code	string	Código do motivo da disputa	Não
issuer	string	Banco emissor do cartão	Não
installment_number	number | null	Parcela atual	Não
installment_count	number | null	Total de parcelas	Não
status	string	Status inicial do alerta. Sempre pending no recebimento	Sim
received_at	string	Quando a Rapid recebeu o alerta (ISO 8601)	Sim
expires_at	string | null	Prazo para resposta (ISO 8601), aplicável apenas a Ethoca	Não
merchant	object | null	Dados do merchant associado (veja abaixo); null se o alerta ainda não foi associado	Sim

Objeto merchant

Campo	Tipo	Descrição
id	string (UUID)	ID do merchant na Rapid
name	string	Nome do merchant

---

Exemplo 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

Disparado quando a Rapid recebe uma disputa de fraude. As bandeiras exigem que o lojista tente revogar o produto ou serviço entregue ao portador e tenha processo para evitar reincidência (Visa Core Rules §10.4.4.3). Quanto mais rápido o corte, menor o prejuízo: trate este evento de forma automática se possível.

O campo merchant diz qual das suas lojas vendeu: a entrega é sempre no webhook único da empresa, você roteia internamente.

Estrutura do corpo

Campo	Tipo	Descrição	Obrigatório
event	string	dispute.fraud.revoke_access	Sim
dispute_id	string (UUID)	ID da disputa na Rapid. Use como chave de idempotência; a disputa aparece no painel, em Disputas	Sim
merchant	object | null	Loja associada (id, name); null se a disputa ainda não foi associada	Sim
network	string	Bandeira: visa, mastercard, …	Sim
condition	string | null	Condição/reason da bandeira (ex.: 10.4, 4837)	Não
transaction_id	string | null	ID da transação na rede, quando informado pela adquirente	Não
customer_ref	string | null	Identificador do cliente que você enviou na transação (account_id), quando existir	Não
order_ref	string	Referência do pedido: número do pedido, seu ID externo ou, na falta deles, o dispute_id	Sim
reason	string	Sempre fraud_dispute_received	Sim
is_account_takeover	boolean	true quando há indício de conta tomada (dispositivo e IP divergem do histórico do cliente)	Sim
required_actions	string[]	Ações exigidas: revoke_access, prevent_reoccurrence e, em conta tomada, re_authenticate	Sim
citation	object	Regra que fundamenta a exigência (section, visa_id, page, quote_en, ruleset_version)	Sim
emitted_at	string	Quando a Rapid emitiu o evento (ISO 8601)	Sim
deadline_hint	string	Prazo de resposta da disputa (ISO 8601) ou as_soon_as_possible quando não há prazo conhecido	Sim

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

Confirmando o que você fez (opcional)

Responder 200 já encerra a entrega. Se quiser registrar o que foi feito, retorne no corpo um JSON com os campos abaixo. Ele aparece no painel, na disputa, como confirmação da sua integração. Chave desconhecida invalida o corpo inteiro (a entrega continua válida, só não registra a confirmação).

Campo	Tipo	Descrição
status	string	done, partial, refused, not_applicable ou accepted
actions_taken	string[]	Quais das required_actions você executou
revoked_at	string	Quando o acesso foi cortado (ISO 8601)
note	string	Observação livre, até 500 caracteres

{
  "status": "done",
  "actions_taken": ["revoke_access", "prevent_reoccurrence"],
  "revoked_at": "2026-09-30T14:25:03Z",
  "note": "conta suspensa e cartao bloqueado para novas compras"
}

Idempotência: a Rapid emite um evento por disputa (dispute_id é único). Retentativas repetem o mesmo dispute_id, então trate pela chave em vez de contar chamadas. Se não conseguirmos entregar, a disputa aparece no painel com a pendência de revogação, e o cliente confirma manualmente ali.

---

Resposta esperada

Sua aplicação deve retornar um dos seguintes códigos para confirmar o recebimento:

Código	Significado
2xx	Sucesso. 200, 201, 202 e 204 valem igual; o corpo é opcional

Qualquer outro código (incluindo 4xx e 5xx) é tratado como falha e dispara retentativa. Cadastre a URL final: um 301, 302 ou 303 na sua URL conta como falha (ver Redirecionamento). Ver Retries e logs.

Em dispute.fraud.revoke_access o corpo do 200 pode trazer a confirmação do que você executou (ver acima). Nos demais eventos o corpo é ignorado.

---

Campos que podem evoluir

Novos campos podem ser adicionados ao payload no futuro. Sua aplicação deve ignorar campos desconhecidos em vez de falhar. Nunca altere ou remova campos ao processar, apenas leia.

---

Formato legacy

Contas migradas do sistema anterior recebem o mesmo POST de antes. Headers: Content-Type: application/json, x-source: rapid, clientid, clientkey, e sem X-Webhook-Signature, X-Webhook-Event ou X-Webhook-Reference-Id.

Campo	Tipo	Descrição
alert_id	string	ID do alerta no provedor (não é o UUID da Rapid). É o valor a usar em POST /chargeback-alert/get e no alias POST /chargeback-alert/update/status
merchant	string	Nome do merchant
provider	string	ethoca ou verifi-rdr
descriptor	string	Nome na fatura do portador
transaction_date	string	Data da transação (ISO 8601)
currency	string	ISO 4217
amount	number | null	Valor da transação
card_number	string | null	BIN******LAST4, ou null quando o provedor não informou BIN e final
created_at	string	Quando a Rapid recebeu o alerta
arn	string | null	Acquirer Reference Number
authorization_code	string | null	Código de autorização
issuer	string | null	Banco emissor
type	string | null	Tipo do alerta
global	boolean	true para alerta internacional
reason_code, status_code, mcc, tier, caid	string | null	Campos do provedor, quando existirem
installment_number, total_installment_count	number | null	Parcelamento

Não há campo event, status nem expires_at neste formato. Retentativas, timeout e logs são os mesmos do v2.