Webhooks FAQ

This FAQ gathers the most common questions about Asaas Webhooks and complements the other documentation contents.

It is recommended both for those starting a new integration and for those who want to understand specific behaviors related to event delivery, queues, idempotency, and failure handling.

If this is your first integration, we recommend reading the Introduction, Webhook Creation, and Receiving Events guides before consulting this page.

Which HTTP status code should my webhook return?

For an event to be considered successfully delivered, your application must return HTTP 200.

Any other status code (3xx, 4xx, 5xx, etc.) will be treated as a failure and will start the queue penalty process.

📘

Important

Although there are several success codes in the 2xx family, Asaas currently considers only HTTP 200 as a successful event processing response.

See also:

• Paused Queue
• Queue Penalty

Does Asaas retry failed deliveries?

Yes.

Whenever a failure occurs, Asaas automatically retries the delivery.

The retry intervals increase progressively until the queue is interrupted after 15 consecutive failures.

Even when interrupted, events remain stored for up to 14 days.

See also:

• Queue Penalty
• Paused Queue

Can the same webhook be delivered more than once?

Yes.

Due to availability and retry mechanisms, the same event may be delivered multiple times.

For this reason, we recommend implementing idempotency using the event id.

Example:

{
  "id": "evt_123456",
  "event": "PAYMENT_RECEIVED"
}

If event evt_123456 has already been processed, it should be ignored.

See also:

• How to Implement Idempotency in Webhooks

Are events delivered in the order they occurred?

It depends on the configured delivery type.

Sequential

Events are delivered in the same order in which they occurred.

Example:

PAYMENT_CREATED
↓
PAYMENT_CONFIRMED
↓
PAYMENT_RECEIVED

Non-sequential

Events are delivered in parallel, prioritizing throughput and performance.

In this mode, there is no guarantee of ordering between different events.

See also:

• Delivery Types

Can I process the webhook and respond afterward?

Yes.

The recommended approach is to return HTTP 200 as quickly as possible and perform processing in the background.

Example:

Receive webhook
↓
Save event to queue
↓
Return HTTP 200
↓
Process event asynchronously

This reduces the risk of timeouts.

See also:

• Error 408 – Read Timed Out

What is the maximum response time?

Asaas waits up to 10 seconds for your server to respond.

If this timeout is exceeded, the attempt is considered a failure.

See also:

• Error 408 – Read Timed Out

How long are events stored?

Events remain available for up to 14 days.

If the queue stays interrupted beyond this period, older events will be permanently deleted.

⚠️

Important

Deleted events cannot be recovered.

See also:

• Webhook Logs
• Paused Queue

Where can I inspect webhook errors?

Go to:

Integrations → Webhook Logs

There you can view:

• returned HTTP status code;
• date and time of the attempt;
• payload sent;
• error message;
• delivery status.

See also:

• Webhook Logs

Does Asaas send a Bearer Token with webhooks?

No.

Asaas Webhooks do not use standard Bearer Token authentication.

If your application requires authentication, we recommend implementing your own validation mechanism.

Does Asaas follow HTTP redirects?

No.

The following responses are not automatically followed:

• 301
• 302
• 307
• 308

The configured URL must respond directly to the POST request sent by the webhook.

See also:

• Other Errors

Which Content-Type is used?

Events are sent with:

Content-Type: application/json

Your endpoint must be prepared to receive JSON payloads.

How can I avoid duplicate events?

We recommend:

• using the id field as an idempotency key;
• storing already processed events;
• ignoring retries.

See also:

• How to Implement Idempotency in Webhooks

What happens if my server returns an error?

The event will be retried.

Consecutive failures trigger progressive penalties and, after 15 unsuccessful attempts, the queue is interrupted.

See also:

• Queue Penalty
• How to Reactivate an Interrupted Queue

What does error 403 mean?

It means the request was blocked before processing.

The most common causes are:

• Cloudflare;
• WAF;
• Firewall;
• IP restrictions;
• internal validations.

See also:

• Error 403 (Forbidden)
• Cloudflare Firewall Blocking
• Official Asaas IP Addresses

What does error 404 mean?

It means the configured URL was not found.

The most common causes are:

• incorrect URL;
• removed endpoint;
• changed route.

See also:

• Error 404 (Not Found)

What does error 408 mean?

It means the application took longer than 10 seconds to respond.

See also:

• Error 408 – Read Timed Out

What does error 500 mean?

It means an internal exception occurred on the application's server.

See also:

• Error 500 (Internal Server Error)

Can I use a firewall to allow requests only from Asaas?

Yes.

You can use the official Asaas IP addresses to create allowlist rules.

See also:

• Official Asaas IP Addresses
• Cloudflare Firewall Blocking

Is there a difference between Sandbox and Production?

Yes.

Additional IP addresses may be used in the Sandbox environment.

Therefore, if you use a firewall or Cloudflare, it is important to validate both environments.

See also:

• Official Asaas IP Addresses

How do I know if my integration is healthy?

A healthy integration typically has:

• HTTP 200 responses;
• an active queue;
• a low number of errors in the logs;
• idempotent processing;
• asynchronous handling;
• endpoint monitoring;
• a low number of penalized events.

Recommended reading order

If you are starting a Webhook integration, we recommend the following sequence:

1. Introduction
2. Create a New Webhook Through the Web Application
3. Create a New Webhook Through the API
4. Receive Asaas Events on Your Endpoint
5. How to Implement Idempotency in Webhooks
6. Polling vs. Webhooks
7. Delivery Types
8. Webhook Logs
9. Queue Penalty
10. Paused Queue
11. Webhooks FAQ