You can use Webhooks so that your system is notified about changes that occur in account registration status.

The events notified by Asaas are:

• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_APPROVED - Bank account approved.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_AWAITING_APPROVAL - Bank account under review.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_PENDING - Bank account returned to pending status.
• ACCOUNT_STATUS_BANK_ACCOUNT_INFO_REJECTED - Bank account rejected.
• ACCOUNT_STATUS_COMMERCIAL_INFO_APPROVED - Commercial information approved.
• ACCOUNT_STATUS_COMMERCIAL_INFO_AWAITING_APPROVAL - Commercial information under review.
• ACCOUNT_STATUS_COMMERCIAL_INFO_PENDING - Commercial information returned to pending status.
• ACCOUNT_STATUS_COMMERCIAL_INFO_REJECTED - Commercial information rejected.
• ACCOUNT_STATUS_DOCUMENT_APPROVED - Documents approved.
• ACCOUNT_STATUS_DOCUMENT_AWAITING_APPROVAL - Documents under review.
• ACCOUNT_STATUS_DOCUMENT_PENDING - Documents returned to pending status.
• ACCOUNT_STATUS_DOCUMENT_REJECTED - Documents rejected.
• ACCOUNT_STATUS_GENERAL_APPROVAL_APPROVED - Account approved.
• ACCOUNT_STATUS_GENERAL_APPROVAL_AWAITING_APPROVAL - Account under review.
• ACCOUNT_STATUS_GENERAL_APPROVAL_PENDING - Account returned to pending status.
• ACCOUNT_STATUS_GENERAL_APPROVAL_REJECTED - Account rejected.

Events related to annual confirmation of commercial information:

• ACCOUNT_STATUS_COMMERCIAL_INFO_EXPIRING_SOON - Commercial information is close to expiring.
• ACCOUNT_STATUS_COMMERCIAL_INFO_EXPIRED - Commercial information has expired.

When to use

Account status Webhooks are recommended when your application needs to automatically track changes in account registration status.

Some examples:

• onboarding tracking;
• automatic feature enablement;
• subaccount monitoring;
• CRM and ERP updates;
• customer notifications;
• annual commercial data confirmation management.

Important behaviors

Asaas Webhooks follow the at least once delivery model, meaning the same event may be resent.

For this reason, we recommend implementing idempotency using the field:

id

In addition:

• HTTP responses outside the 2xx family may trigger new delivery attempts;
• the queue may be interrupted after consecutive failures;
• events remain available for up to 14 days;
• new attributes may be added in the future.

Example JSON received [POST]

The notification consists of a POST containing a JSON, as shown below:

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "ACCOUNT_STATUS_COMMERCIAL_INFO_APPROVED",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "accountStatus": {
        "id": "175027c1-029c-41e5-8b9a-e289b9788c33",
        "commercialInfo": "APPROVED",
        "bankAccountInfo": "APPROVED",
        "documentation": "APPROVED",
        "general": "APPROVED"
    }
}

Important fields

👍

Webhook response with typing and ENUMs

If you want to know the type of each field and the available ENUM values, check the 200 response of the endpoint "Get account status" in the documentation.

Security

We recommend:

• validating the asaas-access-token header;
• responding quickly using HTTP 200;
• processing events asynchronously;
• implementing idempotency using the event identifier;
• monitoring Webhook Logs;
• allowing new attributes in the payload without causing exceptions.

Common errors

Duplicate event

Webhooks follow the at least once delivery model. The same event may be resent.

Use the id field to avoid duplicate processing.

HTTP response outside the 2xx range

Responses outside the 2xx family may trigger new delivery attempts and eventual queue interruption.

Unknown fields

New attributes may be added in the future.

Your application should ignore unknown fields to maintain compatibility.

Operational impacts

Failures during processing may cause:

• new delivery attempts;
• synchronization queue interruption;
• inconsistencies between systems;
• delays in updating account status;
• permanent loss of events after 14 days.

🚧

Attention

• As new products and features are introduced into Asaas, new attributes may be added to the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes not handled by your application, as this may cause synchronization queue interruption.
• We will send an email and notify our Discord whenever new fields are added to the Webhook. Notifications will be sent to the email address configured in the Webhook settings.