DiscordStatus
Guias / Guides

Paused Queue

When a communication failure occurs between Asaas and the configured endpoint, the event is not immediately discarded.

Asaas performs new delivery attempts using a progressive penalty mechanism. If 15 consecutive failures occur, the queue for that Webhook is automatically interrupted to avoid continuously sending requests to an unavailable endpoint.

The interruption occurs per Webhook configuration. Other Webhooks configured in the account continue to operate normally.

How event delivery works

Whenever a change occurs in an integrated resource, Asaas sends a POST request to the configured URL.

For the delivery to be considered successful, the endpoint must return:

HTTP 200 OK
📘

Important

Although all HTTP 2xx status codes represent success according to the HTTP protocol, Asaas considers only HTTP 200 responses as successful deliveries.

Any other response (201, 204, 308, 400, 403, 404, 500, etc.) will be interpreted as a communication failure.

What happens when failures occur?

After a failure, Asaas keeps retrying the same event.

If 15 consecutive attempts fail:

  • the queue for that Webhook is interrupted;
  • new events continue to be generated normally;
  • events remain stored;
  • no new events will be delivered until the queue is reactivated.

You will receive email notifications throughout this process.

What happens to events while the queue is paused?

Even when the queue is paused:

  • events continue to be generated;
  • events are temporarily stored;
  • once the queue is reactivated, accumulated events are resent in the same order they were stored;
  • events older than 14 days are permanently deleted.
🚧

Attention

If the queue remains interrupted for more than 14 days, the oldest events will be permanently removed and cannot be recovered.

Example flow

PAYMENT_CREATED
↓
Endpoint returns HTTP 500
↓
Asaas retries
↓
15 consecutive failures
↓
Queue interrupted
↓
New events continue to be generated
↓
Issue is fixed
↓
Queue is reactivated
↓
Accumulated events are resent

How to identify that the queue has been interrupted

You will receive automatic email notifications informing you about delivery failures.

You can also verify the queue status at:

Integrations → Webhooks

The affected configuration will display the interrupted queue status.

How to identify the root cause

The best approach is to inspect the Webhook logs.

See:

How to view Webhook Logs

The logs allow you to identify:

  • returned HTTP status codes;
  • error messages;
  • timestamps of delivery attempts;
  • payload sent;
  • number of retries performed.

HTTP status codes and Webhook behavior

HTTP 200 - Success

Indicates that the event was processed successfully.

Result: the event is considered delivered and removed from the queue.

HTTP 3xx - Redirection

The endpoint attempted to redirect the request to another URL.

Asaas does not automatically follow redirects.

Result: the delivery fails and the event enters the retry cycle.

HTTP 4xx - Client error

Usually indicates:

  • incorrect URL;
  • invalid authentication;
  • payload validation errors;
  • blocked requests.

Result: the event will continue to be retried until the maximum number of attempts is reached.

HTTP 5xx - Internal server error

Indicates that the endpoint received the request but could not process it.

Common causes include:

  • server unavailability;
  • timeout;
  • application exceptions;
  • database unavailability.

Result: the event will continue to be retried automatically.

Best practices

📘

Recommended

  • Always return HTTP 200 after processing the event.
  • Process Webhooks asynchronously.
  • Implement idempotency to support retries.
  • Monitor Webhook Logs regularly.
  • Fix the root cause before reactivating the queue.
  • Avoid leaving the queue interrupted for more than 14 days.

Guides for specific errors

If you encounter an error in the logs, refer to:

Next steps

After understanding how an interrupted queue works, we recommend reading: