# Visão geral

> Como a Rapid entrega alertas e eventos no seu sistema por webhook HTTPS: cadastro da URL, chave de assinatura e fluxo de entrega.

Página: https://doc.rapidchargeback.com/canais/webhook/visao-geral/

A Rapid entrega alertas e eventos para o sistema do cliente via **webhook HTTPS POST**. Sua aplicação expõe uma URL, a Rapid envia requisições para ela cada vez que houver um alerta a notificar.

Webhook é o mecanismo universal de entrega. Hoje dois produtos usam o canal:

- **Alerta**: `chargeback_alert.received`: um alerta novo chegou.
- **Disputa**: `dispute.fraud.revoke_access`: chegou uma disputa de fraude e a bandeira exige cortar o acesso do portador.

A URL é uma só; o campo `event` (e o header `X-Webhook-Event`) diz qual evento chegou. Qualquer produto futuro usa o mesmo canal.

Internamente os provedores são identificados por slugs em payloads e respostas: `ethoca_alerts` (Mastercard) e `verifi_rdr` (Visa).

## Fluxo resumido

1. Você cadastra a URL do seu endpoint no painel da Rapid; a Rapid gera a chave de assinatura e mostra uma única vez
2. Quando um alerta é recebido e associado à sua empresa, a Rapid enfileira a entrega
3. A Rapid faz `HTTP POST` para sua URL com o payload do evento
4. Sua aplicação valida a assinatura do header `X-Webhook-Signature`, processa o evento e retorna `200` ou `204`
5. Se sua aplicação retornar erro ou não responder, a Rapid tenta novamente (ver [Retries e logs](https://doc.rapidchargeback.com/canais/webhook/retries-e-logs/))

## Configuração

- Cada empresa pode ter **um webhook ativo por vez**.
- A chave de assinatura (`secret`) é gerada pela Rapid no cadastro, mostrada **uma única vez** e usada para validar a assinatura HMAC-SHA256. Perdeu? Peça uma nova ao suporte (a anterior deixa de valer).
- Se o webhook estiver inativo, os eventos continuam sendo armazenados e ficam visíveis no painel, mas não são entregues. Uma revogação de acesso não entregue aparece como pendência na disputa, para tratamento manual.

## Próximos passos

- [Payload](https://doc.rapidchargeback.com/canais/webhook/payload/): estrutura completa do body enviado.
- [Autenticação](https://doc.rapidchargeback.com/canais/webhook/autenticacao/): como validar `X-Webhook-Signature`.
- [Retries e logs](https://doc.rapidchargeback.com/canais/webhook/retries-e-logs/): política de retentativas.
- [Boas práticas](https://doc.rapidchargeback.com/canais/webhook/boas-praticas/): idempotência, timeout, resposta rápida.