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é seu endpoint, mas foi bloqueada por alguma regra de segurança, geralmente relacionada a firewall, WAF ou validações internas.

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 (ex: Cloudflare) estão impedindo a requisição
• o servidor rejeita requisições com determinados headers
• há validações internas que recusam a origem da requisição

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 vindas do Asaas.

Recomendado:

• liberar tráfego proveniente dos IPs oficiais do Asaas
• evitar regras genéricas que bloqueiem requisições externas

⚠️

Em ambiente sandbox, podem existir IPs adicionais.

2. Verificar regras de WAF (ex: Cloudflare)

Se você utiliza soluções como Cloudflare, verifique:

• regras de bloqueio por país
• regras de rate limit
• regras de bot protection
• regras customizadas (Firewall Rules)

Se necessário, crie uma regra permitindo requisições para seu endpoint de webhook.

3. Validar o header User-Agent

O Asaas envia requisições com o seguinte header:

• 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-Agent desconhecidos
• ambos os ambientes estão contemplados nas regras de segurança

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

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

• bloqueio por token ou autenticação obrigatória
• validação de origem (IP allowlist)
• validações de assinatura ou segurança

Importante:

O webhook do Asaas não envia autenticação padrão (como Bearer Token), então qualquer validação desse tipo pode causar bloqueio.

Exemplo de cenário comum

Sua aplicação está protegida por Cloudflare com regras de segurança padrão.

Quando o Asaas envia o webhook:

• a requisição chega até o Cloudflare
• o WAF interpreta como tráfego suspeito
• a requisição é bloqueada
• o Asaas registra erro 403 no log

Solução:

• criar uma regra liberando o endpoint de webhook
• ou permitir os IPs do Asaas
• garantir que tanto Asaas_Prod/3.0 quanto Asaas_Sandbox/3.0 não sejam bloqueados

Como validar se funcionou

Após realizar os ajustes:

1. Reative a fila de webhooks no Asaas
2. Gere um novo evento (ex: pagamento)
3. Verifique os logs novamente

Se corrigido:

• o status deixará de ser 403
• os eventos serão processados corretamente pela sua aplicação

Erros comuns

• liberar apenas IPs de produção e esquecer o sandbox
• não considerar diferença de User-Agent entre ambientes
• bloquear requisições por ausência de autenticação
• não validar regras do provedor (Cloudflare, AWS WAF, etc)
• não analisar logs do servidor (apenas logs do Asaas)

Boas práticas

• manter uma allowlist atualizada dos IPs do Asaas
• considerar ambos ambientes (sandbox e produção)
• evitar validações rígidas de User-Agent
• monitorar logs do endpoint de webhook
• implementar fallback ou retry seguro no processamento

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 status 200 OK
• revisar o fluxo completo de webhook (recebimento → processamento → persistência)