Queue Penalty

To ensure the stability of the Webhook system and provide predictability regarding delivery attempts, Asaas uses a progressive penalty mechanism. Whenever the configured endpoint starts returning failures, new deliveries begin to follow increasing retry intervals.

This behavior prevents overload both on the Asaas side and on the application experiencing issues, allowing the integrator enough time to identify and fix the root cause.

This mechanism applies to Webhooks configured in both Sequential and Non-Sequential modes.

When does the penalty occur?

The penalty occurs whenever the Webhook endpoint returns a response outside the HTTP 2xx family, for example:

• 400 Bad Request
• 403 Forbidden
• 404 Not Found
• 408 Read Timed Out
• 500 Internal Server Error
• Connection failures
• Timeouts

Each failed attempt increases the interval before the next retry.

How does the penalty work?

After the first failure, Asaas automatically starts a progressive retry cycle:

After 15 consecutive failures, the Webhook queue will be interrupted.

What happens when the queue is paused?

When the queue is paused:

• New events continue to be generated normally.
• Events remain stored in the queue.
• No new deliveries are performed until the queue is reactivated.
• Events remain available for up to 14 days.
• Events older than 14 days are permanently deleted.

📘

Important

Queue interruption occurs per Webhook configuration. If multiple Webhooks are configured, the others will continue operating normally.

Impact of Sequential mode

In Sequential mode, event ordering is guaranteed.

This means that if one event is under penalty, all subsequent events in that queue will remain waiting until the current event is successfully delivered.

Example:

PAYMENT_CREATED
↓
PAYMENT_CONFIRMED
↓
PAYMENT_RECEIVED
↓
PAYMENT_REFUNDED

If the PAYMENT_CONFIRMED delivery is under penalty, the PAYMENT_RECEIVED and PAYMENT_REFUNDED events will not be sent until the pending event is successfully processed.

📘

Important

If your application depends on the chronological order of events, we recommend using Sequential delivery.

Penalty flow

Event sent
↓
Endpoint error
↓
Automatic retry
↓
Progressive intervals
↓
15 consecutive failures
↓
Queue paused
↓
Issue fixed
↓
Penalty removed
↓
Deliveries resumed

Removing the penalty

After identifying and fixing the issue in your application, you do not need to wait until the retry cycle finishes.

You can request Asaas to remove the penalty and immediately retry the first event in the queue.

Through the web application

Go to:

Integrations → Webhooks

There is a column next to the status displaying the number of penalized events.

1. Open the Webhook containing penalized events.
2. Click Remove penalty.
3. Confirm the action.

Through the API

You can also remove the penalty programmatically using the dedicated endpoint.

See the complete endpoint reference

🚧

Attention

This endpoint has a stricter rate limit to discourage automations that continuously remove penalties.

It is intended to be used only after the issue causing the failures has been fixed.

Best practices

📘

Recommended

• Monitor Webhook Logs regularly.
• Process events asynchronously.
• Ensure your endpoint responds quickly.
• Implement idempotency to support retries.
• Investigate failures before removing the penalty.
• Avoid automating continuous penalty removal.
• Configure alerts to monitor endpoint availability.

Next steps

After understanding how queue penalties work, we recommend reading:

• Delivery types;
• Webhook Logs;
• Paused queue;
• How to reactivate an interrupted queue;
• Error 400 (Bad Request);
• Error 403 (Forbidden);
• Error 404 (Not Found);
• Error 408 (Read Timed Out);
• Error 500 (Internal Server Error);
• Connect Timed Out errors;
• How to implement idempotency in Webhooks.