Error 404 (Not Found)

A 404 Not Found error in the Webhook Logs indicates that the request reached the configured domain, but the server could not find the route used by the Webhook.

This usually happens when the URL is incorrect, has been changed, or no longer exists.

Main causes

Check whether any of these situations occurred:

• a typo in the configured URL;
• the route was changed without updating the Webhook;
• the route responsible for receiving events was removed;
• the domain changed;
• the environment changed, such as Production or staging;
• the application was deployed to a different path;
• a proxy or gateway is forwarding the request to an incorrect route.

For example, if the Webhook is configured with:

https://minhaapi.com/webhook

but the application now uses:

https://minhaapi.com/api/webhook

the previous URL may return HTTP 404.

How to fix it

1. Check the configured URL

Compare the URL registered in the Webhook with the route currently published by the application.

Incorrect URL

https://minhaapi.com/webhook

Correct URL

https://minhaapi.com/api/webhook

Check:

• protocol (https);
• domain;
• port;
• route path;
• uppercase and lowercase letters;
• extra slashes (/).

If the route was changed, update the URL configured in the Webhook.

2. Test the route with POST

Use Postman, cURL, or another HTTP tool to test the same method used by Webhooks.

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

If the response is still:

404 Not Found

check the routing of the application itself, the proxy, or the gateway.

Opening the URL directly in the browser can help check whether the address is reachable, but it does not validate how the route behaves for POST requests.

3. Confirm the route still exists

A new version of the application may change the endpoint path.

Before:

POST /webhook

After:

POST /api/webhook

In this case, update the Webhook configuration to use the new route.

4. Confirm the route accepts POST

Webhook events are sent via POST requests.

Confirm that:

• the route exists;
• the POST method is enabled;
• proxies or gateways forward the request to the correct destination;
• there is no redirect to another URL.

Example of an error after a route change

The application used:

https://api.minhaempresa.com/webhook

After an update, it started using:

https://api.minhaempresa.com/api/webhook

If the Webhook configuration is not updated, the flow may result in:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Asaas sends the Webhook"] --> B["POST /webhook"]
    B --> C["Server returns<br/>404 Not Found"]
    C --> D["Make retries"]
    D --> E["Reach 15 consecutive failures"]
    E --> F["Interrupt the queue"]

    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 404 persists, the event will not be considered delivered and new attempts may occur.

After 15 consecutive failures, the Webhook queue is interrupted. New events continue to be generated and stored, but events that remain pending for more than 14 days are permanently deleted.

Understand Queue penalty.

How to validate the fix

After fixing the route:

1. update the Webhook URL, if necessary;
2. test the endpoint again with a POST request;
3. if the queue is interrupted, reactivate the configuration;
4. generate or wait for a new event;
5. check the Webhook Logs.

The fix is complete when new attempts no longer return 404 and the endpoint responds with HTTP 200.

Next steps

• Check the Webhook Logs
• Review the Webhook endpoint implementation
• Understand Queue penalty
• Understand the Paused queue behavior
• Reactivate an interrupted queue
• See other Webhook errors