Webhooks with queue paused

Asaas uses conventional HTTP responses to indicate success or failure in requests.

When activating the Webhook, whenever there are changes in the integrated resources, a POST request will be made to the configured address, containing the event and the involved resource. For Asaas to consider the notification as successfully processed, the HTTP status of the client application's response must be 200.


Any other return that Asaas receives (whether 308, 404, 403, 500, etc.) is considered a communication failure.

When there is a problem with the sending of Webhooks, you will receive an email from Asaas at the registered email informing you of the issue. After that, Asaas will continue trying to send the same event. If the error occurs 15 times in a row, the sending queue is paused, and you will stop receiving new events until you reactivate the queue in the panel.

Webhook de cobranças com fila de sincronização interrompida.

Payments webhook with broken sync queue

With the queue paused, new events continue to be generated and saved by Asaas, but they are no longer sent to your application until you reactivate it. When reactivated, all accumulated events will be sent in sequence.

See more: How to view Webhook logs

If you encounter any error messages or HTTP response codes in the logs and are unsure how to resolve them, you can consult the guides below:

400 Bad Request

The 400 error generally means that we sent the request, but the system could not receive it due to a difference in the expected formatting, such as an unhandled attribute, or an expected return that is not sent by us.

It's important to check our webhook tabs on the sidebar of the documentation for the model of payload sent by us, and ensure that your system is treating all events and not expecting non-existent attributes.

404 Not Found

The 404 error indicates that the event dispatch was made, but the informed URL did not lead us to an existing location. This can indicate some typing error in the URL, or that the server is inactive or has been moved.

Make sure there are no typing errors in your URL, and also check if the location we are dispatching to is not unavailable or that the server URL has not been changed. After that, simply reconfigure the URL in Asaas and reactivate the queue.

403 Forbidden

This type of return usually occurs when your Firewall is blocking connections from Asaas for information dispatch.

In this case, you need to check your Firewall settings, following these guidelines:

Possible adjustments in your firewall:

We recommend making sure that your firewall will not block requests coming from Asaas. One way to ensure this is to allow all traffic coming from the official Asaas IPs.

Note: in sandbox, there may be other IPs that need to be allowed.

Asaas sends the webhook request with the header: { User-Agent: Java/1.8.0_275 }. Ensure that your firewall provider does not block requests with this header.

After checking and making sure to allow these points, you can reactivate your queue to check if the events will be synchronized.

500 Internal Server Error

The webhook error 500 means that the connection with your server was established, but your application returned an error. This usually occurs due to some exception in your code/technology.

It can indicate an adversity on the server. This may be due to some incompatibility or even incorrect server settings, such as wrong scripts, etc.

The error 500 is a very broad code. But, in general, it means errors on the web server, where it cannot complete the user's request. And the server cannot identify the reason for this.

Read Timed Out

The connection with your server was established, and the event was triggered, but your application did not return the response in the expected time.

At Asaas, we wait for the response for 10 seconds; if no return is received in that time, the webhook is triggered with the error “Read Time Out”. The synchronization is done every 30 seconds, and if your system fails to respond with HTTP 200 15 consecutive times, the synchronization queue will be interrupted.

You will need to check in your system, the time it is taking to return the webhook to us, and if it is above 10 seconds, make the necessary adjustment.

After ensuring that your system will respond with HTTP 200 to Asaas, simply reactivate the synchronization queue by accessing the My Account area, the Integration tab, and all pending events will be processed in chronological order.

Connect timed out

The Connect timed out error means that the connection was not established after reaching the timeout.

Generally, this error is when there is something wrong with your local network connection. However, it's not always the case.

It can also mean that your site is trying to do more than your server can manage. This is particularly common in shared hosting, where your memory limit is restricted.

You will need to check in your system, what may be causing this error and make the correction so that it returns to normal functioning and after that, reactivate the webhook synchronization queue.