Boas práticas
Valide a assinatura antes de tudo
Seção intitulada “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.
Responda rápido
Seção intitulada “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
Seção intitulada “Idempotência”A Rapid pode entregar o mesmo evento mais de uma vez:
- Quando a tentativa anterior falhou (retentativa automática)
- Quando alguém da sua equipe reenvia a entrega pelo painel
- Em casos raros de falha de rede entre a resposta do seu servidor e a confirmação no lado da Rapid
Não conte entregas: seu processamento deve ser idempotente pela referência do evento, o header X-Webhook-Reference-Id (o alert_id no alerta, o dispute_id na revogação de acesso):
- Ao receber um webhook, confira se já existe um registro com essa referência no seu sistema
- Se existir, retorne
200imediatamente, não processe novamente - Se não existir, processe e armazene
No formato legacy esse header não existe: use o alert_id do corpo.
Ordem e status
Seção intitulada “Ordem e status”As entregas podem chegar fora de ordem. A Rapid entrega vários eventos ao mesmo tempo, e uma retentativa chega depois de eventos mais novos. Não deduza a ordem pela chegada: para ordenar alertas, use o received_at do corpo.
Cada entrega leva o status do alerta no momento em que foi montada, e as retentativas repetem o mesmo corpo. O alerta novo chega pending, mas um reenvio pode trazer um alerta que já venceu ou já foi respondido. Antes de agir sobre um alerta, confira o status e o expires_at e, na dúvida, consulte o alerta para ver o status atual.
Ignore campos desconhecidos
Seção intitulada “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 intitulada “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
Seção intitulada “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
Seção intitulada “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. Para conferir o endpoint antes do primeiro alerta, use Enviar evento de teste, em Configurações › Webhook (ver Evento de teste).
Proteja o secret
Seção intitulada “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
Seção intitulada “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)