Webhooks

Webhooks are the mechanism used by Asaas to automatically notify external systems whenever certain events occur in the account.

Instead of making frequent API requests to check for changes, your application can receive real-time notifications whenever events such as payments, subscriptions, transfers, Pix transactions, invoices, or other resources are updated.

Webhooks allow you to build more efficient integrations, reduce unnecessary API requests, and keep different systems automatically synchronized.

When to use

Webhooks are recommended for integrations that need to:

• receive real-time notifications;
• synchronize information automatically;
• update orders, customers, or services after payments;
• track events related to payments, subscriptions, and Pix;
• reduce the need for constant API requests;
• implement event-driven architectures.

This model is recommended for most production integrations.

How it works

In a simplified way, the flow works as follows:

An event occurs in the Asaas account
↓
Asaas identifies the configured webhooks
↓
A notification is sent to the application URL
↓
The system receives the event
↓
The event is processed
↓
The integration updates its data

Each notification contains information related to the resource that originated the event.

Recommended flow

A typical implementation usually follows the journey below:

Create Webhook
↓
Configure the application endpoint
↓
Select monitored events
↓
Receive notifications
↓
Implement idempotency
↓
Monitor logs
↓
Handle failures and interrupted queues

Important concepts

During implementation, some concepts deserve special attention:

• events are sent to a URL configured by the integration;
• processing failures may trigger new delivery attempts;
• responses other than success may cause queue penalties;
• the implementation should be idempotent to prevent duplicate processing;
• firewall mechanisms may block requests coming from Asaas;
• logs allow you to monitor failures and delivery attempts.

Contents of this section

This section gathers content related to Webhook implementation and operation:

Getting started

• Introduction
• Create a new Webhook through the web application
• Create a new Webhook through the API
• Receive Asaas events on your Webhook endpoint

Best practices

• How to implement idempotency in Webhooks
• Polling vs. Webhooks
• Delivery types

Available events

• Webhook events
• Payment events
• Subscription events
• Invoice events
• Transfer events
• Automatic Pix events
• And other API resources

Monitoring and troubleshooting

• Webhook logs
• Queue penalty
• Paused queue
• How to reactivate an interrupted queue
• Errors 400, 403, 404, 408, 500, and others

Infrastructure and security

• Cloudflare Firewall blocking
• Official Asaas IP addresses

Frequently asked questions

• Webhook FAQ

Best practices

• Use Webhooks whenever possible instead of periodic polling.
• Implement idempotent processing.
• Monitor integration logs.
• Ensure that the application properly responds to notifications.
• Periodically validate the configured events.
• Monitor interrupted queues and penalties.

Next steps

If you are starting an event-driven integration, we recommend following this sequence:

1. Introduction.
2. Create a Webhook.
3. Receive events at your endpoint.
4. Implement idempotency.
5. Learn about the available events.
6. Configure monitoring and failure handling.