DiscordStatus
Guias / Guides

Error 403 (Forbidden)

What does it mean?

A 403 Forbidden error in the Webhook logs means that your server received the request sent by Asaas, but denied access.

In practice, this means the request successfully reached the configured endpoint, but some security rule prevented it from being processed.

In most cases, the blockage is related to firewalls, WAFs, internal validations, or IP restrictions.

When does this error occur?

This error commonly happens when:

  • the firewall blocks external requests;
  • IP restrictions are not properly configured;
  • WAF rules (such as Cloudflare) block the request;
  • the server rejects certain headers;
  • internal validations deny the request origin;
  • mandatory authentication is configured on the endpoint;
  • the hosting provider has active protection mechanisms.

How to fix it

Follow the steps below to ensure your endpoint accepts requests from Asaas.

1. Check firewall restrictions

Make sure your firewall allows requests originating from Asaas.

Recommended:

  • allow traffic from the official Asaas IP addresses;
  • avoid generic rules that block external requests;
  • verify whether country or ASN restrictions are enabled.
⚠️

Additional IP addresses may be used in the Sandbox environment.

2. Review WAF rules (Cloudflare, AWS WAF, etc.)

If you use protection services, verify:

  • country-based restrictions;
  • rate limits;
  • Bot Protection settings;
  • custom firewall rules;
  • rules automatically generated by the provider.

If necessary, create a rule allowing requests to your Webhook endpoint.

3. Validate the User-Agent header

Asaas sends requests using the following User-Agents:

Production

User-Agent: Asaas_Prod/3.0

Sandbox

User-Agent: Asaas_Sandbox/3.0

Make sure that:

  • your server does not block these headers;
  • there are no rules rejecting unknown User-Agents;
  • both environments are covered by your security policies.

4. Review internal authentication and validations

If your endpoint performs additional validations, verify:

  • mandatory authentication;
  • token validation;
  • IP allowlists;
  • custom validations;
  • internal security rules.
📘

Important

Asaas Webhooks do not send standard authentication headers such as Bearer Token or Basic Auth. Any validation that requires them may cause the endpoint to return HTTP 403.

Common scenario example

Suppose your application is protected by Cloudflare.

When Asaas sends an event:

Asaas
↓
Cloudflare
↓
WAF identifies the request as suspicious traffic
↓
Request blocked
↓
HTTP 403
↓
Event remains in the queue

Solution:

  • create a rule allowing the Webhook endpoint;
  • allow the official Asaas IP addresses;
  • ensure that Asaas User-Agents are not blocked.

How to verify that it worked

After applying the changes:

  1. Reactivate the Webhook queue.
  2. Generate a new event (payment, charge, or subscription).
  3. Check the logs again.

If the issue is resolved:

  • the status will no longer be 403;
  • events will start being processed normally;
  • the queue will gradually drain.

Common mistakes

  • allowing only production IPs and forgetting Sandbox;
  • blocking unknown User-Agents;
  • requiring Bearer authentication on the endpoint;
  • creating overly restrictive Cloudflare rules;
  • reviewing only Asaas logs and ignoring server logs;
  • forgetting to reactivate the queue after fixing the issue.

Best practices

  • maintain an updated allowlist of Asaas IP addresses;
  • consider both Production and Sandbox environments in security rules;
  • avoid strict User-Agent validations;
  • monitor endpoint logs;
  • implement asynchronous processing;
  • use idempotency to support retries;
  • respond quickly with HTTP 200.

Next step in the flow

After fixing the 403 error, it is recommended to:

  • validate that events are being processed correctly;
  • ensure your application returns HTTP 200;
  • review the entire Webhook flow (receive → process → persist).

Related content

Depending on the source of the blockage, the following articles may help:

  • Cloudflare Firewall Blocking — configuring rules and exceptions in Cloudflare.
  • Official Asaas IP addresses — recommended IP list for allowlists.
  • Paused Queue — queue behavior after multiple consecutive failures.
  • How to Reactivate an Interrupted Queue — steps to restore event delivery.
  • Webhook Logs — view errors recorded by Asaas.
  • Queue Penalty — how automatic retries work.
  • How to Implement Idempotency in Webhooks — best practices for safely handling events.
  • Connect Timed Out Error — when the connection cannot be established.
  • Error 408 (Read Timed Out) — when the server takes too long to respond.

Next steps

If you continue experiencing issues, we recommend consulting: