Subscription events

Use subscription events to track changes in the recurrence lifecycle, such as creation, update, inactivation, removal and behaviors related to Payment Split.

To track the charges generated by the subscription and their payments, use the Payment events.

Available events

Subscription lifecycle

Payment Split

To understand how divergences are handled, see Subscription block flow due to Split divergence.

Subscription events vs. payment events

A subscription generates charges throughout the recurrence. Therefore, the two groups of events have different purposes:

When a subscription charge is created, the PAYMENT_CREATED event contains the subscription field, which lets you identify the originating subscription.

See the Payment events.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Subscription is created or changed"] --> B["Generate subscription event"]
    B --> C["Send the Webhook"]
    C --> D["Persist the event"]
    D --> E["Respond HTTP 200"]
    E --> F["Update the application"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Event payload

The notification is sent via POST and contains the event and the subscription object.

{
  "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

How to handle the events

When receiving a subscription event:

1. identify the change through the event field;
2. persist the id to prevent duplicate processing;
3. use subscription.id to find the subscription in your system;
4. respond HTTP 200 after confirming persistence;
5. process the update asynchronously.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence in Webhooks.

If the order of changes matters to your integration, see Send types.

Handle Split events

When using Split on the subscription:

• SUBSCRIPTION_SPLIT_DISABLED: sync your application to reflect that the Split was disabled;
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK: identify the blocked subscription and follow the flow to resolve the divergence;
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED: update your application after the block ends.

The Split configured on the subscription is applied to the new charges generated by the recurrence.

See:

• Split in subscriptions
• Subscription block flow due to Split divergence

Validate authentication

When the Webhook has a configured token, validate the header:

asaas-access-token

Next steps

• Receive Asaas events at your Webhook endpoint
• Track the events for the subscription's charges
• Implement idempotence in Webhooks
• Understand the block due to Split divergence
• Monitor the Webhook Logs