Queue penalty

When a Webhook endpoint has consecutive failures, Asaas progressively increases the interval between delivery attempts.

This mechanism applies to Webhooks with both Sequential and Non-Sequential delivery.

When the penalty is applied

A delivery is considered successful when the endpoint responds with a 2xx success code, such as 200, 201, 202, or 204. For Webhooks configured with an API version earlier than 3, the response body must also contain SUCCESS.

Any other result is considered a failure, for example:

• 400 Bad Request;
• 403 Forbidden;
• 404 Not Found;
• 408 Read Timed Out;
• 500 Internal Server Error;
• connection failures;
• timeouts.

Each consecutive failure increases the interval until the next attempt.

Retry intervals

After 15 consecutive failures, the Webhook queue is interrupted.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
A["Send event"] --> B["Receive failure"]
B --> C["Apply new attempt"]
C --> D["Increase interval"]
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

When the queue is interrupted

After the interruption:

• new events continue to be generated;
• events are stored in the queue;
• no new deliveries are made until reactivation;
• events remain stored for up to 14 days;
• events older than 14 days are permanently deleted.

Fix the cause of the failure before reactivating the queue.

See how to reactivate an interrupted queue.

Impact on Sequential delivery

In Sequential mode, events follow the order in which they occurred. If an event is penalized, the subsequent events in that queue wait for its delivery.

Example:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED"]
B --> C["PAYMENT_RECEIVED"]
C --> D["PAYMENT_REFUNDED"]

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 validacao
class D sucesso

linkStyle default stroke:#94A3B8,stroke-width:2px

If PAYMENT_CONFIRMED is penalized, PAYMENT_RECEIVED and PAYMENT_REFUNDED will remain waiting.

To compare the two behaviors, see Delivery types.

Remove the penalty after fixing the endpoint

If the configuration is still penalized but the cause of the failure has already been fixed, you can remove the backoff without waiting for the next automatic interval.

Removing the penalty should not be confused with reactivating a queue that has already been interrupted. When the queue reaches 15 failures and is interrupted, use the reactivation flow.

Via the web application

Go to Integrations → Webhooks.

1. find the Webhook with penalized events;
2. click Remove penalty;
3. confirm the action.

Asaas may retry the delivery without waiting for the remaining penalty interval.

Via the API

Use:

POST /v3/webhooks/{id}/removeBackoff

An HTTP 204 response confirms the penalty removal.

See the Remove webhook backoff endpoint.

Next steps

• Check the Webhook Logs
• Understand the paused queue behavior
• Reactivate an interrupted queue
• Learn about the delivery types
• Implement idempotency in Webhooks