DiscordStatus
Guias / Guides

Erro 403 (Forbidden)

O que fazer quando vejo este erro nos logs de Webhooks do Asaas?

O que significa

O erro 403 (Forbidden) nos logs de Webhooks indica que o servidor da sua aplicação recebeu a requisição do Asaas, mas recusou o acesso.

Na prática, isso significa que a comunicação chegou até o endpoint configurado, porém alguma regra de segurança impediu que a requisição fosse processada.

Na maioria dos casos, esse bloqueio está relacionado a firewall, WAF, validações internas ou restrições por IP.

Quando esse erro acontece

Esse erro normalmente ocorre quando:

  • o firewall bloqueia requisições externas;
  • há restrições por IP não configuradas corretamente;
  • regras de WAF (como Cloudflare) impedem a requisição;
  • o servidor rejeita determinados headers;
  • existem validações internas que recusam a origem da requisição;
  • há autenticações obrigatórias configuradas no endpoint;
  • o provedor de hospedagem possui mecanismos de proteção ativos.

Como resolver

Siga os passos abaixo para garantir que seu endpoint aceite corretamente as requisições do Asaas.

1. Validar bloqueio por firewall

Certifique-se de que seu firewall permite requisições provenientes do Asaas.

Recomendado:

  • liberar tráfego proveniente dos IPs oficiais do Asaas;
  • evitar regras genéricas que bloqueiem requisições externas;
  • validar se existe alguma política de bloqueio por país ou ASN.
⚠️

Em ambiente Sandbox podem existir IPs adicionais.

2. Verificar regras de WAF (Cloudflare, AWS WAF, etc.)

Se você utiliza soluções de proteção, verifique:

  • regras de bloqueio por país;
  • rate limits;
  • Bot Protection;
  • Firewall Rules customizadas;
  • regras geradas automaticamente pelo provedor.

Caso necessário, crie uma regra permitindo requisições destinadas ao endpoint do webhook.

3. Validar o header User-Agent

O Asaas envia requisições utilizando os seguintes User-Agents:

Produção

User-Agent: Asaas_Prod/3.0

Sandbox

User-Agent: Asaas_Sandbox/3.0

Certifique-se de que:

  • seu servidor não bloqueia esses headers;
  • não existem regras que rejeitam User-Agents desconhecidos;
  • ambos os ambientes estão contemplados nas regras de segurança.

4. Validar autenticações ou verificações internas

Se o endpoint possui validações adicionais, verifique:

  • autenticação obrigatória;
  • validação por token;
  • IP allowlist;
  • validações customizadas;
  • regras internas de segurança.
📘

Importante

O Webhook do Asaas não envia autenticação padrão (Bearer Token, Basic Auth, etc.). Qualquer validação desse tipo poderá fazer com que o endpoint responda HTTP 403.

Exemplo de cenário comum

Sua aplicação está protegida pelo Cloudflare.

Quando o Asaas envia um evento:

Asaas
↓
Cloudflare
↓
WAF interpreta como tráfego suspeito
↓
Requisição bloqueada
↓
HTTP 403
↓
Evento permanece na fila

Solução:

  • criar uma regra permitindo o endpoint do webhook;
  • liberar os IPs do Asaas;
  • garantir que os User-Agents do Asaas não sejam bloqueados.

Como validar se funcionou

Após realizar os ajustes:

  1. Reative a fila de Webhooks.
  2. Gere um novo evento (pagamento, cobrança ou assinatura).
  3. Consulte os logs novamente.

Se corrigido:

  • o status deixará de ser 403;
  • os eventos voltarão a ser processados normalmente;
  • a fila será esvaziada gradualmente.

Erros comuns

  • liberar apenas os IPs de produção e esquecer o Sandbox;
  • bloquear User-Agents desconhecidos;
  • exigir autenticação Bearer no endpoint;
  • criar regras excessivamente restritivas no Cloudflare;
  • analisar apenas os logs do Asaas e ignorar os logs do próprio servidor;
  • esquecer de reativar a fila após a correção.

Boas práticas

  • manter uma allowlist atualizada dos IPs do Asaas;
  • considerar produção e Sandbox nas regras de segurança;
  • evitar validações rígidas de User-Agent;
  • monitorar os logs do endpoint;
  • implementar processamento assíncrono;
  • utilizar idempotência para suportar reenvios;
  • responder rapidamente com HTTP 200.

Próximo passo no fluxo

Após resolver o erro 403, é recomendado:

  • validar o processamento correto dos eventos recebidos;
  • garantir que sua aplicação responde com HTTP 200;
  • revisar todo o fluxo de webhook (recebimento → processamento → persistência).

Conteúdos relacionados

Dependendo da origem do bloqueio, os conteúdos abaixo podem ajudar na investigação e correção do problema: