Boas práticas

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

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)