Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

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.

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.

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):

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

No formato legacy esse header não existe: use o alert_id do corpo.

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.

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.

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.

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.

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).

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

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)