Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

EventoProdutoQuando disparaCorpo
chargeback_alert.receivedAlertaUm alerta foi recebido e associado à sua empresaAlerta recebido
dispute.fraud.revoke_accessDisputaChegou uma disputa de fraude (Visa 10.4 / Mastercard 4837) e a bandeira exige que você corte o acesso do portadorRevogação de acesso
webhook.testTesteAlguém da sua equipe clicou em Enviar evento de teste, em Configurações › WebhookEvento de teste

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.

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


CampoTipoDescriçãoObrigatório
eventstringchargeback_alert.receivedSim
alert_idstring (UUID)ID único do alerta na Rapid, use para chamar os endpoints de consulta e atualização de statusSim
provider_alert_idstringID do alerta no sistema do provedor. Útil para cross-referência em caso de suporte direto com o provedorSim
providerstringOrigem do alerta: ethoca_alerts ou verifi_rdrSim
amountnumber | nullValor da transação disputada (pode vir null quando o provedor não informa)Sim
currencystringCódigo ISO 4217 com 3 letras maiúsculasSim
card_last4stringÚltimos 4 dígitos do cartãoSim
card_binstringBIN do cartão (6-8 dígitos)Sim
transaction_datestringData da transação original (ISO 8601, "2026-04-01T00:00:00.000Z")Sim
descriptorstringNome exibido na fatura do portadorSim
arnstringAcquirer Reference NumberNão
caidstringCard Acceptor IDNão
auth_codestringCódigo de autorização da transaçãoNão
alert_typestringTipo do alerta (ex: fraud, dispute)Não
reason_codestringCódigo do motivo da disputaNão
issuerstringBanco emissor do cartãoNão
installment_numbernumber | nullParcela atualNão
installment_countnumber | nullTotal de parcelasNão
statusstringStatus do alerta quando a entrega foi montada. Na chegada de um alerta novo, pending. Num reenvio, ou num alerta que chegou sem a sua empresa identificada e foi associado depois, vem o status daquele momento (por exemplo expired ou account_suspended). Ver Ordem e statusSim
received_atstringQuando a Rapid recebeu o alerta (ISO 8601)Sim
expires_atstring | nullPrazo para resposta (ISO 8601), aplicável apenas a EthocaNão
merchant_enrollment_idstring (UUID) | nullO enrollment que casou com o alerta; null quando o alerta foi associado sem enrollmentSim
merchantobject | nullDados do merchant associado (veja abaixo); null se o alerta ainda não foi associadoSim
CampoTipoDescrição
idstring (UUID)ID do merchant na Rapid
namestringNome do merchant
merchant_refstring | nullA referência do merchant no seu sistema (ver Criar ou atualizar merchant); null quando o merchant não tem

merchant_enrollment_id e merchant.merchant_ref só existem no formato v2: o formato legacy não muda. Se a referência for gravada depois que a entrega do alerta começou, as retentativas dessa entrega ainda levam null: a consulta de alertas traz o valor atual.


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

Disparado quando a Rapid recebe uma disputa de fraude e identifica a loja que vendeu. Se a disputa chegar sem a loja identificada, o evento sai assim que ela for associada. Também sai quando a disputa de fraude foi evitada antes de virar chargeback: nesse caso dispute_status vem prevented e não há defesa a fazer, mas o corte de acesso vale do mesmo jeito. Num inquérito de fraude (o banco só pediu informações, ainda sem chargeback) o evento não sai: ele sai se o inquérito virar chargeback 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.

CampoTipoDescriçãoObrigatório
eventstringdispute.fraud.revoke_accessSim
dispute_idstring (UUID)ID da disputa na Rapid. Use como chave de idempotência; a disputa aparece no painel, em DisputasSim
dispute_statusstringSituação da disputa quando o evento foi montado: received, submitted, won, lost, accepted ou prevented. prevented quer dizer que a disputa foi evitada antes de virar chargeback e não há defesa a fazerSim
merchantobjectLoja que vendeu (id, name)Sim
networkstringBandeira: visa, mastercard, …Sim
conditionstring | nullCondição/reason da bandeira (ex.: 10.4, 4837)Não
transaction_idstring | nullID da transação na rede, quando informado pela adquirenteNão
customer_refstring | nullIdentificador do cliente que você enviou na transação (account_id), quando existirNão
order_refstringReferência do pedido: número do pedido, seu ID externo ou, na falta deles, o dispute_idSim
reasonstringSempre fraud_dispute_receivedSim
is_account_takeoverbooleantrue quando há indício de conta tomada (dispositivo e IP divergem do histórico do cliente)Sim
required_actionsstring[]Ações exigidas: revoke_access, prevent_reoccurrence e, em conta tomada, re_authenticateSim
citationobjectRegra que fundamenta a exigência (section, visa_id, page, quote_en, ruleset_version)Sim
emitted_atstringQuando a Rapid emitiu o evento (ISO 8601)Sim
deadline_hintstringPrazo de resposta da disputa (ISO 8601) ou as_soon_as_possible quando não há prazo conhecidoSim
{
"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 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).

CampoTipoDescrição
statusstringdone, partial, refused, not_applicable ou accepted
actions_takenstring[]Quais das required_actions você executou
revoked_atstringQuando o acesso foi cortado (ISO 8601)
notestringObservaçã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.


Sai quando alguém da sua equipe clica em Enviar evento de teste, em Configurações › Webhook. Serve para conferir o endpoint antes do primeiro alerta: chega na URL cadastrada com os mesmos headers e a mesma assinatura das entregas reais, o painel mostra na hora o código que a sua URL respondeu, e a tentativa fica no Histórico de entregas.

Não é um alerta: não cria nada na Rapid, não gera cobrança e não traz dado de cartão. Trate pelo event e responda 2xx. Se a sua integração só processa chargeback_alert.received, responder 200 sem processar basta.

CampoTipoDescriçãoObrigatório
eventstringwebhook.testSim
testbooleanSempre trueSim
test_idstring (UUID)ID deste teste: o mesmo valor do header X-Webhook-Reference-Id, diferente a cada envioSim
emitted_atstringQuando a Rapid enviou o teste (ISO 8601)Sim
{
"event": "webhook.test",
"test": true,
"test_id": "0193f0c2-7a4e-7b1d-9c3e-5f2a8d6b4e10",
"emitted_at": "2026-11-03T14:00:00.000Z"
}

O teste sai uma vez, sem retentativa, com o mesmo timeout de 30 segundos, e vale com o webhook ativo ou desativado. Contas no formato legacy não recebem o evento de teste: nesse formato o corpo não diz o tipo do evento, e o teste seria lido como alerta.


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

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


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.


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.

CampoTipoDescrição
alert_idstringID 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
merchantstringNome do merchant
providerstringethoca ou verifi-rdr
descriptorstringNome na fatura do portador
transaction_datestringData da transação (ISO 8601)
currencystringISO 4217
amountnumber | nullValor da transação
card_numberstring | nullBIN******LAST4, ou null quando o provedor não informou BIN e final
created_atstringQuando a Rapid recebeu o alerta
arnstring | nullAcquirer Reference Number
authorization_codestring | nullCódigo de autorização
issuerstring | nullBanco emissor
typestring | nullTipo do alerta
globalbooleantrue para alerta internacional
reason_code, status_code, mcc, tier, caidstring | nullCampos do provedor, quando existirem
installment_number, total_installment_countnumber | nullParcelamento

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