Erro 403 (Forbidden)

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

O erro 403 Forbidden nos Logs de Webhooks indica que a requisição chegou à infraestrutura do seu endpoint, mas alguma regra de segurança recusou o acesso.

As causas mais comuns são firewall, WAF, restrições por IP, autenticação ou validações internas.

Principais causas

Causa	O que verificar
Firewall	Bloqueios de tráfego externo, origem, país ou ASN.
Restrição por IP	Se os IPs oficiais do Asaas estão permitidos.
WAF	Regras de Cloudflare, AWS WAF, Bot Protection ou rate limiting.
User-Agent	Regras que bloqueiam User-Agents desconhecidos.
Autenticação	Exigência de Bearer Token, Basic Auth ou outro mecanismo não utilizado pelo Webhook.
Validação interna	Regras da aplicação ou do provedor de hospedagem que recusam a requisição.

Como corrigir

1. Verifique o firewall e as restrições por IP

Confirme se o firewall permite as requisições enviadas pelo Asaas.

Verifique:

allowlists de IP;
bloqueios por país ou ASN;
regras de Security Groups;
proxies e balanceadores;
políticas que bloqueiam tráfego externo.

Consulte os IPs oficiais do Asaas antes de configurar a allowlist.

⚠️
Em ambiente Sandbox podem existir IPs adicionais.

Se o 403 ocorrer somente no Sandbox, consulte também os eventos do seu firewall ou WAF para identificar os IPs bloqueados nesse ambiente.

2. Verifique as regras do WAF

Se utilizar Cloudflare, AWS WAF ou solução semelhante, revise:

bloqueios por país;
rate limits;
Bot Protection;
regras personalizadas de firewall;
regras automáticas do provedor;
restrições relacionadas ao User-Agent.

Se o bloqueio ocorrer no Cloudflare, consulte Bloqueio do Firewall na CloudFlare.

3. Verifique o User-Agent

O Asaas utiliza os seguintes User-Agents nos Webhooks.

Produção

User-Agent: Asaas_Prod/3.0

Sandbox

User-Agent: Asaas_Sandbox/3.0

Confirme que sua infraestrutura não bloqueia esses valores nem exige uma lista restrita de User-Agents diferente da utilizada pelo Asaas.

4. Verifique a autenticação do endpoint

Revise qualquer autenticação ou validação aplicada à rota do Webhook, como:

Bearer Token;
Basic Auth;
validação por token próprio;
IP allowlist;
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.

Se você configurou um authToken no Webhook, o Asaas envia esse valor pelo header asaas-access-token. Utilize esse header para validar a notificação em vez de exigir Bearer Token ou Basic Auth.

Consulte como configurar um Webhook pela API.

Exemplo de bloqueio pelo WAF

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas envia o Webhook"] --> B["Cloudflare recebe a requisição"]
    B --> C["WAF identifica<br/>tráfego suspeito"]
    C --> D["Bloquear a requisição"]
    D --> E["Retornar HTTP 403"]
    E --> F["Evento permanece pendente"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Enquanto o endpoint continuar retornando 403, o evento entra no mecanismo de retentativas e penalização da fila.

Após 15 falhas consecutivas, a fila daquele Webhook pode ser interrompida.

Como validar a correção

Após ajustar as regras de segurança:

consulte os Logs de Webhooks;
se a fila estiver interrompida, reative a configuração;
gere ou aguarde um novo evento;
confirme que o endpoint recebeu a requisição;
verifique nos logs se a entrega deixou de retornar 403.

A entrega é considerada bem-sucedida quando o endpoint retorna HTTP 200.

Se o erro continuar, compare o horário registrado nos Logs de Webhooks com os logs do firewall, WAF, proxy e aplicação para identificar qual camada está recusando a requisição.

Próximos passos

Updated 5 days ago

Did this page help you?