​
Token na query string

Opcionalmente a plataforma exige ?token= na URL do webhook, configurável nas definições gerais do gateway (painel admin) e nas variáveis de ambiente do servidor (nomes em .env.example). Exemplo: 
POST https://seu-dominio.com/api/webhooks/bspay?token=SEU_TOKEN_SECRETO

​
Obrigar token em produção

Quando o token de query estiver configurado no painel, ative no servidor a variável de ambiente que exige esse token nas requisições de webhook (documentada em .env.example). Enquanto nenhum token estiver definido, ativar essa exigência faz os webhooks responderem 403, evitando POST forjados sem segredo compartilhado.

​
Limite de taxa e corpo

  • Os endpoints /api/webhooks/bspay e /api/webhooks/gateway têm rate limit por IP (configurável no .env.example).
  • O tamanho máximo do corpo também é configurável no .env.example (padrão da ordem de centenas de KB).
  • Apenas Content-Type JSON é aceito quando há corpo (evita payloads disfarçados).

​
HTTPS

Use sempre HTTPS em produção.

​
Idempotência

Eventos podem ser reenviados. Trate atualização de status e efeitos colaterais de forma idempotente (mesmo payload não deve corromper estado).

​
IPs de origem

Se precisar restringir por IP de origem, alinhe com o provedor de liquidação ou a operação da sua infraestrutura; a NavePay expõe o endpoint de recebimento e as políticas de rede ficam a cargo do seu ambiente.