Events for subscriptions

It is possible to use Webhook so that your system is notified about changes that occur in subscriptions.

Subscription events allow you to track creation, updates, inactivation, deletion, and behaviors related to Payment Split in subscriptions.

The events that Asaas notifies are:

• SUBSCRIPTION_CREATED - New subscription created.
• SUBSCRIPTION_UPDATED - Subscription updated.
• SUBSCRIPTION_INACTIVATED - Subscription inactivated.
• SUBSCRIPTION_DELETED - Subscription deleted.
• SUBSCRIPTION_SPLIT_DISABLED - Subscription split was disabled.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK - Subscription blocked due to split divergence.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED - Subscription block due to split divergence was finished.

When to use

Use subscription events when your integration needs to automatically react to changes in the lifecycle of a subscription.

Some use examples:

• grant or block access to a recurring service;
• update the subscription status in your system;
• synchronize recurring data between Asaas and an external platform;
• monitor changes in amount, cycle, or payment method;
• track inactivation or deletion of subscriptions;
• handle blocks or changes related to Payment Split.

How it works

Whenever a subscription undergoes a relevant change, Asaas sends an HTTP POST request to the URL configured in the Webhook.

The flow usually works like this:

Subscription is created or updated
↓
Subscription event is generated
↓
Asaas sends a POST request
↓
Your application receives the payload
↓
The integration processes the event
↓
The endpoint returns HTTP 2xx

Example JSON to be received [POST]

The notification consists of a POST containing a JSON, as shown in this example:

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "SUBSCRIPTION_CREATED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "subscription": {
    "object": "subscription",
    "id": "sub_m5gdy1upm25fbwgx",
    "dateCreated": "2024-10-16",
    "customer": "cus_000000008773",
    "paymentLink": null,
    "value": 19.9,
    "nextDueDate": "2024-11-22",
    "cycle": "MONTHLY",
    "description": "Pro Plan Subscription",
    "billingType": "BOLETO",
    "deleted": false,
    "status": "ACTIVE",
    "externalReference": null,
    "sendPaymentByPostalService": false,
    "discount": {
      "value": 10,
      "limitDate": null,
      "dueDateLimitDays": 0,
      "type": "PERCENTAGE"
    },
    "fine": {
      "value": 1,
      "type": "PERCENTAGE"
    },
    "interest": {
      "value": 2,
      "type": "PERCENTAGE"
    },
    "split": [
      {
        "walletId": "a0188304-4860-4d97-9178-4da0cde5fdc1",
        "fixedValue": null,
        "percentualValue": 20,
        "externalReference": null,
        "description": null
      }
    ]
  }
}

Important payload fields

Some fields are especially relevant for processing subscription events:

📘

Important

Use the event id field to avoid duplicate processing and the subscription.id field to identify which subscription should be updated in your system.

Important behaviors

When processing subscription events, consider that:

• events are sent via HTTP POST request;
• delivery follows the at least once model, therefore the same event may be sent more than once;
• your application must implement idempotency using the event identifier;
• the endpoint must return an HTTP status code in the 2xx range to indicate success;
• responses different from 2xx may trigger new delivery attempts;
• after consecutive failures, the synchronization queue may be interrupted;
• pending events remain available for up to 14 days;
• new attributes may be added to the payload over time.

Security

When receiving subscription events, it is recommended to validate whether the request was sent by Asaas.

To do this, use the token configured in the Webhook and validate the header:

asaas-access-token

It is also recommended to restrict request reception to the official Asaas IPs, when applicable.

📘

Recommended

Never use the Asaas API Key as the Webhook authentication token.

Best practices

• Process events asynchronously.
• Respond HTTP 2xx as quickly as possible.
• Implement idempotency based on the event id.
• Use subscription.id as the main subscription identifier.
• Do not rely on the order of receipt for critical processing without internal validation.
• Monitor Webhook Logs.
• Prepare your application to receive new fields in the payload.
• Configure only the events required for your integration.

Common errors

Duplicate event

This may occur because delivery follows the at least once model.

Use the event id to ensure idempotency.

Endpoint returns an error

When the endpoint returns an error outside the 2xx range, the event may be resent and the queue may be penalized.

Subscription not found in the internal system

This may occur when the subscription identifier has not yet been saved in your application.

Use subscription.id and, if applicable, externalReference for reconciliation.

Webhook authentication failure

This may occur when the asaas-access-token header is not validated correctly or when the configured token has been changed.

Operational impacts

Subscription events can directly impact the granting, blocking, or updating of recurring services in your application.

Processing failures may cause:

• divergence between the subscription status in Asaas and in your system;
• improper access granting;
• incorrect blocking of active customers;
• duplicate processing;
• interruption of the synchronization queue.

For this reason, it is recommended to monitor received events and handle failures quickly.

👍

Webhook return with typing and ENUMs

If you want to know the type of each field and the available ENUM returns, check the 200 response in the endpoint "Retrieve a single subscription" in the documentation.

🚧

Attention

• With the introduction of new products and features in 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 interruption of the synchronization queue.

  • We will send an email and notify on our Discord when new fields are added to the Webhook. The notification will be sent to the notification email defined in the webhook settings.
  • The split array will be returned only when the subscription has Payment Split configured.

Related content

• Webhook Events;
• Receive events from Asaas on your Webhook endpoint;
• How to implement idempotency in Webhooks;
• Webhook Logs;
• Queue penalties;
• Paused queue;
• Payment Split.

It is possible to use Webhook so that your system is notified about changes that occur in subscriptions.

Subscription events allow you to track creation, updates, inactivation, deletion, and behaviors related to Payment Split in subscriptions.

The events that Asaas notifies are:

• SUBSCRIPTION_CREATED - New subscription created.
• SUBSCRIPTION_UPDATED - Subscription updated.
• SUBSCRIPTION_INACTIVATED - Subscription inactivated.
• SUBSCRIPTION_DELETED - Subscription deleted.
• SUBSCRIPTION_SPLIT_DISABLED - Subscription split was disabled.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK - Subscription blocked due to split divergence.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED - Subscription block due to split divergence was finished.

When to use

Use subscription events when your integration needs to automatically react to changes in the lifecycle of a subscription.

Some use examples:

• grant or block access to a recurring service;
• update the subscription status in your system;
• synchronize recurring data between Asaas and an external platform;
• monitor changes in amount, cycle, or payment method;
• track inactivation or deletion of subscriptions;
• handle blocks or changes related to Payment Split.

How it works

Whenever a subscription undergoes a relevant change, Asaas sends an HTTP POST request to the URL configured in the Webhook.

The flow usually works like this:

Subscription is created or updated
↓
Subscription event is generated
↓
Asaas sends a POST request
↓
Your application receives the payload
↓
The integration processes the event
↓
The endpoint returns HTTP 2xx

Example JSON to be received [POST]

The notification consists of a POST containing a JSON, as shown in this example:

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "SUBSCRIPTION_CREATED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "subscription": {
    "object": "subscription",
    "id": "sub_m5gdy1upm25fbwgx",
    "dateCreated": "2024-10-16",
    "customer": "cus_000000008773",
    "paymentLink": null,
    "value": 19.9,
    "nextDueDate": "2024-11-22",
    "cycle": "MONTHLY",
    "description": "Pro Plan Subscription",
    "billingType": "BOLETO",
    "deleted": false,
    "status": "ACTIVE",
    "externalReference": null,
    "sendPaymentByPostalService": false,
    "discount": {
      "value": 10,
      "limitDate": null,
      "dueDateLimitDays": 0,
      "type": "PERCENTAGE"
    },
    "fine": {
      "value": 1,
      "type": "PERCENTAGE"
    },
    "interest": {
      "value": 2,
      "type": "PERCENTAGE"
    },
    "split": [
      {
        "walletId": "a0188304-4860-4d97-9178-4da0cde5fdc1",
        "fixedValue": null,
        "percentualValue": 20,
        "externalReference": null,
        "description": null
      }
    ]
  }
}

Important payload fields

Some fields are especially relevant for processing subscription events:

📘

Important

Use the event id field to avoid duplicate processing and the subscription.id field to identify which subscription should be updated in your system.

Important behaviors

When processing subscription events, consider that:

• events are sent via HTTP POST request;
• delivery follows the at least once model, therefore the same event may be sent more than once;
• your application must implement idempotency using the event identifier;
• the endpoint must return an HTTP status code in the 2xx range to indicate success;
• responses different from 2xx may trigger new delivery attempts;
• after consecutive failures, the synchronization queue may be interrupted;
• pending events remain available for up to 14 days;
• new attributes may be added to the payload over time.

Security

When receiving subscription events, it is recommended to validate whether the request was sent by Asaas.

To do this, use the token configured in the Webhook and validate the header:

asaas-access-token

It is also recommended to restrict request reception to the official Asaas IPs, when applicable.

📘

Recommended

Never use the Asaas API Key as the Webhook authentication token.

Best practices

• Process events asynchronously.
• Respond HTTP 2xx as quickly as possible.
• Implement idempotency based on the event id.
• Use subscription.id as the main subscription identifier.
• Do not rely on the order of receipt for critical processing without internal validation.
• Monitor Webhook Logs.
• Prepare your application to receive new fields in the payload.
• Configure only the events required for your integration.

Common errors

Duplicate event

This may occur because delivery follows the at least once model.

Use the event id to ensure idempotency.

Endpoint returns an error

When the endpoint returns an error outside the 2xx range, the event may be resent and the queue may be penalized.

Subscription not found in the internal system

This may occur when the subscription identifier has not yet been saved in your application.

Use subscription.id and, if applicable, externalReference for reconciliation.

Webhook authentication failure

This may occur when the asaas-access-token header is not validated correctly or when the configured token has been changed.

Operational impacts

Subscription events can directly impact the granting, blocking, or updating of recurring services in your application.

Processing failures may cause:

• divergence between the subscription status in Asaas and in your system;
• improper access granting;
• incorrect blocking of active customers;
• duplicate processing;
• interruption of the synchronization queue.

For this reason, it is recommended to monitor received events and handle failures quickly.

👍

Webhook return with typing and ENUMs

If you want to know the type of each field and the available ENUM returns, check the 200 response in the endpoint "Retrieve a single subscription" in the documentation.

🚧

Attention

• With the introduction of new products and features in 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 interruption of the synchronization queue.

  • We will send an email and notify on our Discord when new fields are added to the Webhook. The notification will be sent to the notification email defined in the webhook settings.
  • The split array will be returned only when the subscription has Payment Split configured.

Related content

• Webhook Events;
• Receive events from Asaas on your Webhook endpoint;
• How to implement idempotency in Webhooks;
• Webhook Logs;
• Queue penalties;
• Paused queue;
• Payment Split.