DiscordStatus
Guias / Guides

Error 404 (Not Found)

What does it mean?

A 404 Not Found error in the Webhook logs indicates that the request sent by Asaas successfully reached the configured domain, but the path (endpoint) could not be found by the server.

In other words, the URL configured to receive events no longer exists, has changed, or is incorrect.

Example:

https://myapi.com/webhook

If the application was changed to use:

https://myapi.com/api/webhook

the old address will return HTTP 404 and events will stop being processed.

When does this error occur?

The most common causes are:

  • a typo in the configured URL;
  • changing the application's endpoint without updating Asaas;
  • removal of the route responsible for receiving webhooks;
  • domain changes;
  • switching between environments (production or staging);
  • publishing the application under a different path;
  • proxy or gateway rules redirecting requests incorrectly.

Impact on the integration

As long as the endpoint keeps returning HTTP 404:

  • events will not be processed;
  • Asaas will continue retrying according to the queue penalty policy;
  • after 15 consecutive failures, the queue will be interrupted;
  • new events will continue to be generated and accumulated;
  • events that remain unprocessed for more than 14 days will be permanently deleted.

For this reason, the issue should be fixed as soon as possible.

How to fix it

1. Validate the configured URL

Verify that the URL configured in the webhook exactly matches the endpoint exposed by your application.

Example:

Incorrect URL

https://myapi.com/webhook

Correct URL

https://myapi.com/api/webhook

Check:

  • protocol (https);
  • domain;
  • port number;
  • route path;
  • uppercase and lowercase characters;
  • unnecessary trailing slashes (/).

2. Test the endpoint manually

Open the URL in a browser or use tools such as Postman or cURL.

Example:

curl -X POST https://myapi.com/api/webhook

If the response is:

404 Not Found

the issue is in the application itself and not on the Asaas side.

3. Verify that the route still exists

After deploying a new version of the application, the route may have changed.

Example:

Before:

POST /webhook

After:

POST /api/webhook

In this case, simply update the webhook URL configured in Asaas.

4. Validate that the endpoint accepts POST requests

Asaas Webhooks are sent using HTTP POST requests.

Make sure that:

  • the route exists;
  • it accepts the POST method;
  • there are no rules redirecting the request to another address.
📘

Important

Asaas considers a webhook successfully delivered only when it receives an HTTP 200 response.

Common scenario example

Suppose the application originally exposed the endpoint:

https://api.mycompany.com/webhook

After an update, it changed to:

https://api.mycompany.com/api/webhook

Since the webhook configuration in Asaas was not updated, all attempts started returning HTTP 404.

Result:

Asaas
↓
POST /webhook
↓
404 Not Found
↓
Automatic retries
↓
Queue interrupted

Solution:

  • update the webhook URL;
  • reactivate the queue;
  • allow accumulated events to be resent.

Best practices

  • keep webhook URLs stable;
  • avoid changing production endpoints without updating Asaas;
  • monitor server logs;
  • use separate environments for staging and production;
  • test the route after new deployments;
  • implement endpoint monitoring.

How to verify that it worked

After fixing the issue:

  1. Update the webhook URL if necessary.
  2. Reactivate the interrupted queue.
  3. Generate a new event.
  4. Check the Webhook logs.

If everything is working properly:

  • events will start being processed again;
  • the queue will gradually drain;
  • logs will no longer show HTTP 404 errors.

Next steps

If you continue experiencing issues, we recommend consulting: