# Boas práticas

> O que um endpoint de webhook precisa fazer: validar a assinatura, responder rápido, ser idempotente, usar HTTPS e endereço público.

Página: https://doc.rapidchargeback.com/canais/webhook/boas-praticas/

## Valide a assinatura antes de tudo

Calcule e confira `X-Webhook-Signature` **antes** de parsear o JSON ou acessar o banco. Qualquer requisição com assinatura inválida deve ser descartada. Ver [Autenticação](https://doc.rapidchargeback.com/canais/webhook/autenticacao/).

## Responda rápido

Retorne `200` ou `204` o quanto antes, idealmente em menos de 1 segundo. Se você precisa processar o alerta (ex: atualizar banco, chamar API do gateway), faça isso de forma assíncrona depois de responder.

O timeout é de 30 segundos por tentativa. Qualquer atraso consome esse orçamento e pode disparar retentativa desnecessária.

## Idempotência

A Rapid pode reenviar o mesmo alerta:
- Quando a tentativa anterior falhou (retentativa automática)
- Quando um alerta é reenviado manualmente pela equipe da Rapid
- Em casos raros de falha de rede entre a resposta do seu servidor e a confirmação no lado da Rapid

Seu processamento deve ser **idempotente por `alert_id`**:

1. Ao receber um webhook, confira se já existe um registro com esse `alert_id` no seu sistema
2. Se existir, retorne `200` imediatamente, não processe novamente
3. Se não existir, processe e armazene

## Ignore campos desconhecidos

O payload pode evoluir com novos campos. Sua deserialização deve **tolerar campos extras** em vez de falhar. Nunca remova ou altere campos ao processar.

## Retorne 200 mesmo em erro de validação

Se o payload chega mas você não consegue processar (ex: merchant não existe no seu lado), **ainda assim retorne 200**. Retornar erro dispara retentativa inútil.

Registre a falha no seu lado (log, alerta interno, fila de erros) e trate offline.

## Use sempre HTTPS

A URL do webhook precisa ser `https://`: o painel não aceita salvar uma URL `http://`, e a Rapid não entrega em HTTP puro. A assinatura prova que a requisição veio da Rapid, mas não cifra o conteúdo, e o payload leva dados do cartão (BIN e últimos 4 dígitos) e da compra.

## Use um endereço público de internet

A URL precisa apontar para um servidor alcançável pela internet. A Rapid não entrega em endereço de rede local ou privada: `localhost`, `127.0.0.1`, `10.x`, `172.16.x` a `172.31.x`, `192.168.x` e equivalentes em IPv6. O painel já recusa esses endereços no cadastro, e um nome de domínio que resolva para um deles falha na hora da entrega.

Para testar a integração na sua máquina, exponha o servidor local com um túnel HTTPS (como ngrok ou Cloudflare Tunnel) e cadastre o endereço público que ele gera.

## Proteja o secret

O `secret` usado para validar `X-Webhook-Signature` deve ser tratado como credencial sensível:
- Não comitar em repositório
- Não logar
- Armazenar em variável de ambiente ou cofre de segredos

## Monitoramento

Recomendamos instrumentar:
- Taxa de webhooks recebidos (se cair, algo pode estar errado na Rapid ou na rede)
- Taxa de assinaturas inválidas (se subir, pode indicar rotação de secret não propagada ou tentativa de forjamento)
- Latência de processamento (para garantir que está abaixo do timeout de 30s)
- Taxa de retentativas entregues (indica problemas no seu lado)