A Webhook is an automated way of sending information between systems whenever certain events occur. When you enable a Webhook, it will send POST requests to the configured address whenever a specific event occurs. This request will include information about the event and the related resource.

Why use Webhooks?

If you want payment data or customer information to always remain synchronized with your application, Webhooks are the best solution. They work as a "reverse API", where Asaas performs an HTTP REST call to your application.

To enable Webhook events, you need to configure the URL that will receive the events. This can be done through the interface by accessing the web application, or via API. You can register up to 10 different Webhook URLs, and for each one you can define which events you want to receive.

Example of a received notification

When an event occurs, Asaas sends a POST request to the configured URL containing information about the event and the related resource.

Example:

{
  "id": "evt_123456789",
  "event": "PAYMENT_RECEIVED",
  "dateCreated": "2026-06-19 14:30:00",
  "payment": {
    "object": "payment",
    "id": "pay_080225913252",
    "customer": "cus_000005913252",
    "value": 150.00,
    "netValue": 148.35,
    "billingType": "PIX",
    "status": "RECEIVED"
  }
}

Your application must interpret the received information and execute the necessary actions according to the integration logic.

📘

Important

The structure of the object sent varies depending on the type of event received. See the "Webhook Events" section to learn about all available events.

Example endpoint response

After processing the notification, it is recommended to return a successful HTTP response:

HTTP/1.1 200 OK

or

HTTP/1.1 204 No Content

Responses outside the 2xx range are interpreted as delivery failures and may trigger retries and, in recurring cases, interruption of the synchronization queue.

Enabling a Webhook

To enable Webhooks, access the Asaas Integrations area, open the Webhooks tab, and provide the URL of your application that will receive the POST requests from Asaas. You can also configure Webhooks via API. See the guides below:

• Create a new Webhook through the web application
• Create a new Webhook through the API

Best practices for using Webhooks

Use these practices to ensure your Webhook integration is secure and works properly.

Handle duplicate events

Webhooks guarantee "at least once" delivery. This means your endpoint may occasionally receive the same webhook event more than once. You can ignore duplicate events by using idempotency. One way to do this is by recording events that have already been processed and ignoring them if they are sent again. Each event sent by Webhooks has its own ID, which remains the same if it is the same event.

Configure only the event types required by your application

Configure only the event types required by your application for each Webhook. Receiving additional event types (or all event types) overloads your server and is not recommended.

Process events asynchronously

You may face scalability issues if you process events synchronously, or host overload problems during traffic spikes. Therefore, it is recommended to implement asynchronous event queue processing.

Verify that events originated from Asaas

To prevent your application from accepting requests from other sources, you can use a token to authenticate requests coming from Asaas. This token can be configured in the Webhook settings. The configured token will be sent in all notifications through the asaas-access-token header.

Return a successful response as quickly as possible

For Asaas to consider the notification successfully processed, the HTTP response status must be greater than or equal to 200 and less than 300. Synchronization happens every time an event changes, and if your system fails to return a successful response 15 consecutive times, the synchronization queue will be interrupted. New notifications will continue to be generated and added to the synchronization queue, but they will not be sent to your application. Once you ensure that your system can return a successful response to Asaas, simply reactivate the synchronization queue in My Account > Integrations. It is also possible to reactivate it using the Update existing webhook endpoint by sending the interrupted attribute as false. All pending events will be processed in chronological order.

Follow our tutorial to receive events from Asaas in your Webhook.

Be aware of possible communication failures

If your application returns any HTTP response outside the 200 range for all delivery attempts, your event queue will be interrupted, and you will receive an email notification from Asaas informing you about the issue. Keep an eye on this to avoid synchronization problems.

❗️

Attention

• Asaas stores Webhook events for 14 days. You will receive an email if there is any communication problem and your Webhooks stop working.
• If your queue is paused, it is extremely important to resolve the issue within 14 days to avoid losing important information.
• Events that remain in the queue for more than 14 days will be permanently deleted.