Eventos para assinaturas

Use os eventos de assinatura para acompanhar alterações no ciclo de vida da recorrência, como criação, atualização, inativação, remoção e comportamentos relacionados ao Split de Pagamentos.

Para acompanhar as cobranças geradas pela assinatura e seus pagamentos, utilize os Eventos para cobranças.

Eventos disponíveis

Ciclo de vida da assinatura

Split de Pagamentos

Para entender o tratamento de divergências, consulte Fluxo de bloqueio de assinatura por divergência de Split.

Eventos de assinatura x eventos de cobrança

Uma assinatura gera cobranças ao longo da recorrência. Por isso, os dois grupos de eventos possuem finalidades diferentes:

Quando uma cobrança da assinatura é criada, o evento PAYMENT_CREATED contém o campo subscription, que permite identificar a assinatura de origem.

Consulte os Eventos para cobranças.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Assinatura é criada ou alterada"] --> B["Gerar evento de assinatura"]
    B --> C["Enviar o Webhook"]
    C --> D["Persistir o evento"]
    D --> E["Responder HTTP 200"]
    E --> F["Atualizar a aplicação"]

    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

Payload do evento

A notificação é enviada via POST e contém o evento e o objeto subscription.

{
  "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": "Assinatura Plano Pró",
    "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
      }
    ]
  }
}

Campos importantes do payload

Como tratar os eventos

Ao receber um evento de assinatura:

1. identifique a alteração pelo campo event;
2. persista o id para impedir processamento duplicado;
3. utilize subscription.id para localizar a assinatura no seu sistema;
4. responda HTTP 200 após confirmar a persistência;
5. processe a atualização de forma assíncrona.

Os Webhooks seguem o modelo at least once, portanto um mesmo evento pode ser enviado mais de uma vez.

Consulte como implementar idempotência em Webhooks.

Se a ordem das alterações for relevante para sua integração, consulte Tipos de envio.

Trate eventos de Split

Ao utilizar Split na assinatura:

• SUBSCRIPTION_SPLIT_DISABLED: sincronize sua aplicação para refletir que o Split foi desativado;
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK: identifique a assinatura bloqueada e siga o fluxo de regularização da divergência;
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED: atualize sua aplicação após o encerramento do bloqueio.

O Split configurado na assinatura é utilizado nas novas cobranças geradas pela recorrência.

Consulte:

• Split em assinaturas
• Fluxo de bloqueio de assinatura por divergência de Split

Valide a autenticação

Quando o Webhook possuir um token configurado, valide o header:

asaas-access-token

Próximos passos

• Receba eventos do Asaas no seu endpoint de Webhook
• Acompanhe os eventos das cobranças da assinatura
• Implemente idempotência em Webhooks
• Entenda o bloqueio por divergência de Split
• Monitore os Logs de Webhooks