Webhooks Guide

Check the Webhooks guide for more information.

This endpoint allows you to create a new webhook to receive automatic notifications about events that occur in your Asaas account.

Webhooks are used to keep systems synchronized without the need for frequent API requests. Whenever a configured event occurs, a notification will be sent to the registered URL.

When to use

This endpoint is recommended for integrations that need to react automatically to platform events, such as:

• payment confirmations;
• invoice due dates;
• cancellations;
• refunds;
• subscription changes;
• events related to Pix, transfers, and other API resources.

Instead of constantly querying API resources, it is recommended to use webhooks to receive real-time updates.

Dependencies

Before creating a webhook, it is necessary to:

• have an active Asaas account;
• have valid API authentication;
• provide a publicly accessible URL;
• define which events should be monitored;
• have an application capable of processing the received notifications.

Without these conditions, the webhook cannot be created properly.

Webhook events

When configuring the webhook, you must specify which events should generate notifications.

📘

Available events

Check the complete list of supported events to define which notifications will be received.

Parameters used

📘

Important

The authToken parameter must contain between 32 and 255 characters and should be stored securely.

Operation behavior

After creating the webhook, the flow follows the behavior below:

Webhook created
↓
Event occurs in the Asaas account
↓
Asaas sends the notification
↓
Application processes the event
↓
Integration updates its data

Webhooks have a unique identifier (id) returned upon creation.

This identifier can later be used to:

• retrieve webhook settings;
• update an existing webhook;
• remove a webhook;
• list webhooks configured in the account.

Notifications are sent to the configured URL, and the receiving system must be prepared to process incoming events.

🚧

Attention

It is recommended that event processing be idempotent, preventing duplicate actions if the same event is received more than once.

Request example

{
  "name": "Payment webhook",
  "url": "https://www.yourapplication.com/webhooks/asaas",
  "email": "[email protected]",
  "enabled": true,
  "interrupted": false,
  "apiVersion": 3,
  "authToken": "secure-token-with-more-than-32-characters",
  "sendType": "SEQUENTIALLY",
  "events": [
    "PAYMENT_RECEIVED",
    "PAYMENT_OVERDUE"
  ]
}

In this example, the webhook will be created as active and will send notifications to the configured URL whenever a payment is received or becomes overdue.

Important considerations

🚧

Attention

It is recommended to use a strong authToken to validate the origin of notifications.

In addition:

• the configured URL must be available to receive requests;
• event processing must be idempotent to avoid duplicates;
• the system must respond properly to received notifications;
• it is recommended to monitor synchronization failures and downtime.

Usage example

A common flow consists of:

Create webhook
↓
Select PAYMENT_RECEIVED
↓
Customer makes a payment
↓
Asaas sends the notification
↓
System automatically updates the order

Best practices

• Configure only the events required by your integration.
• Use a dedicated URL to receive Asaas events.
• Validate the received authToken before processing the notification.
• Log received events for auditing and troubleshooting purposes.
• Implement idempotent processing to avoid duplicate actions.
• Monitor delivery failures and webhook queue interruptions.

📘

Important

After creating the webhook, it is recommended to perform tests to ensure that events are being received and processed correctly.

Common errors

Invalid or inaccessible URL

Occurs when the provided URL is not publicly available or does not accept external requests.

Invalid authToken

May occur when the provided token does not meet the minimum requirements or is not properly validated by the receiving application.

Events not configured

May occur when no relevant events have been selected to send notifications.

Interrupted queue

When the synchronization queue is interrupted, events are no longer sent normally.

Duplicate processing

May occur when the receiving application does not implement idempotent event handling.

Operational impacts

Downtime of the configured URL or failures during processing may cause delays in synchronization between systems.

For this reason, it is recommended to:

• monitor webhook deliveries;
• maintain high availability of the receiving application;
• log received notifications;
• validate the authenticity of messages using the authToken;
• monitor possible synchronization queue interruptions.

Next steps

Depending on your integration requirements, the following contents may complement the implementation:

• Retrieve webhook;
• Update webhook;
• Remove webhook;
• Process events received by the integration.

🚧

Attention

Webhooks have an identifier (id). Use this identifier to retrieve, update, or remove the resource later.