Error 403 (Forbidden)

A 403 Forbidden error in the Webhook Logs indicates that the request reached your endpoint's infrastructure, but a security rule denied access.

The most common causes are firewalls, WAFs, IP restrictions, authentication, or internal validations.

Main causes

How to fix it

1. Check the firewall and IP restrictions

Confirm that the firewall allows the requests sent by Asaas.

Check:

• IP allowlists;
• blocks by country or ASN;
• Security Group rules;
• proxies and load balancers;
• policies that block external traffic.

See the official Asaas IPs before configuring the allowlist.

If the 403 only occurs in Sandbox, also check your firewall or WAF events to identify the IPs blocked in that environment.

2. Check the WAF rules

If you use Cloudflare, AWS WAF, or a similar solution, review:

• blocks by country;
• rate limits;
• Bot Protection;
• custom firewall rules;
• automatic provider rules;
• User-Agent-related restrictions.

If the block occurs in Cloudflare, see Cloudflare Firewall Blocking.

3. Check the User-Agent

Asaas uses the following User-Agents in Webhooks.

Production

User-Agent: Asaas_Prod/3.0

Sandbox

User-Agent: Asaas_Sandbox/3.0

Confirm that your infrastructure does not block these values or require a restricted list of User-Agents different from the one used by Asaas.

4. Check the endpoint authentication

Review any authentication or validation applied to the Webhook route, such as:

• Bearer Token;
• Basic Auth;
• custom token validation;
• IP allowlist;
• internal security rules.

If you configured an authToken in the Webhook, Asaas sends this value in the asaas-access-token header. Use this header to validate the notification instead of requiring a Bearer Token or Basic Auth.

See how to configure a Webhook via the API.

Example of a WAF block

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas sends the Webhook"] --> B["Cloudflare receives the request"]
    B --> C["WAF identifies<br/>suspicious traffic"]
    C --> D["Block the request"]
    D --> E["Return HTTP 403"]
    E --> F["Event remains pending"]

    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

While the endpoint keeps returning 403, the event enters the queue retry and penalty mechanism.

After 15 consecutive failures, the queue for that Webhook may be interrupted.

How to validate the fix

After adjusting the security rules:

1. check the Webhook Logs;
2. if the queue is interrupted, reactivate the configuration;
3. generate or wait for a new event;
4. confirm that the endpoint received the request;
5. check in the logs that the delivery no longer returns 403.

The delivery is considered successful when the endpoint returns HTTP 200.

If the error persists, compare the time recorded in the Webhook Logs with the firewall, WAF, proxy, and application logs to identify which layer is rejecting the request.

Next steps

• See the official Asaas IPs
• Resolve Cloudflare Firewall blocks
• Check the Webhook Logs
• Understand queue penalty
• Understand the paused queue behavior
• Reactivate an interrupted queue