Eventos para assinaturas

É possível utilizar Webhook para que o seu sistema seja notificado sobre alterações que ocorram nas assinaturas.

Os eventos de assinatura permitem acompanhar a criação, alteração, inativação, remoção e comportamentos relacionados a Split de Pagamentos em assinaturas.

Os eventos que o Asaas notifica são:

• SUBSCRIPTION_CREATED - Geração de nova assinatura.
• SUBSCRIPTION_UPDATED - Alteração na assinatura.
• SUBSCRIPTION_INACTIVATED - Assinatura inativada.
• SUBSCRIPTION_DELETED - Assinatura removida.
• SUBSCRIPTION_SPLIT_DISABLED - Split da assinatura foi desativado.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK - Assinatura bloqueada por divergência de split.
• SUBSCRIPTION_SPLIT_DIVERGENCE_BLOCK_FINISHED - Bloqueio da assinatura por divergência de split foi finalizado.

Quando utilizar

Utilize os eventos de assinatura quando sua integração precisar reagir automaticamente a mudanças no ciclo de vida de uma assinatura.

Alguns exemplos de uso:

• liberar ou bloquear acesso a um serviço recorrente;
• atualizar o status de uma assinatura no seu sistema;
• sincronizar dados de recorrência entre Asaas e uma plataforma externa;
• monitorar alterações de valor, ciclo ou forma de pagamento;
• acompanhar inativação ou remoção de assinaturas;
• tratar bloqueios ou alterações relacionadas a Split de Pagamentos.

Como funciona

Sempre que uma assinatura sofre uma alteração relevante, o Asaas envia uma requisição HTTP POST para a URL configurada no Webhook.

O fluxo normalmente ocorre assim:

Assinatura é criada ou alterada
↓
Evento de assinatura é gerado
↓
Asaas envia uma requisição POST
↓
Sua aplicação recebe o payload
↓
A integração processa o evento
↓
O endpoint retorna HTTP 2xx

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme este exemplo:

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

Alguns campos são especialmente relevantes para processar eventos de assinatura:

📘

Importante

Utilize o campo id do evento para evitar processamento duplicado e o campo subscription.id para identificar qual assinatura deve ser atualizada no seu sistema.

Comportamentos importantes

Ao processar eventos de assinatura, considere que:

• os eventos são enviados via requisição HTTP POST;
• a entrega segue o modelo at least once, portanto o mesmo evento pode ser enviado mais de uma vez;
• sua aplicação deve implementar idempotência utilizando o identificador do evento;
• o endpoint deve retornar um código HTTP da família 2xx para indicar sucesso;
• respostas diferentes de 2xx podem gerar novas tentativas de entrega;
• após falhas consecutivas, a fila de sincronização poderá ser interrompida;
• os eventos pendentes permanecem disponíveis por até 14 dias;
• novos atributos podem ser incluídos no payload ao longo do tempo.

Segurança

Ao receber eventos de assinatura, recomenda-se validar se a requisição foi enviada pelo Asaas.

Para isso, utilize o token configurado no Webhook e valide o header:

asaas-access-token

Também é recomendado restringir o recebimento das requisições aos IPs oficiais do Asaas, quando aplicável.

📘

Recomendado

Nunca utilize a API Key do Asaas como token de autenticação do Webhook.

Boas práticas

• Processe os eventos de forma assíncrona.
• Responda HTTP 2xx o mais rapidamente possível.
• Implemente idempotência com base no id do evento.
• Utilize subscription.id como identificador principal da assinatura.
• Não dependa da ordem de recebimento para processamentos críticos sem validação interna.
• Monitore os Logs de Webhooks.
• Prepare sua aplicação para receber novos campos no payload.
• Configure apenas os eventos necessários para sua integração.

Erros comuns

Evento duplicado

Pode ocorrer porque a entrega segue o modelo at least once.

Utilize o id do evento para garantir idempotência.

Endpoint retorna erro

Quando o endpoint retorna erro fora da família 2xx, o evento pode ser reenviado e a fila pode ser penalizada.

Assinatura não encontrada no sistema interno

Pode ocorrer quando o identificador da assinatura ainda não foi salvo na sua aplicação.

Utilize subscription.id e, se aplicável, externalReference para conciliação.

Falha de autenticação do Webhook

Pode ocorrer quando o header asaas-access-token não é validado corretamente ou quando o token configurado foi alterado.

Impactos operacionais

Eventos de assinatura podem impactar diretamente a liberação, bloqueio ou atualização de serviços recorrentes na sua aplicação.

Falhas no processamento podem causar:

• divergência entre o status da assinatura no Asaas e no seu sistema;
• liberação indevida de acesso;
• bloqueio incorreto de clientes ativos;
• duplicidade de processamento;
• interrupção da fila de sincronização.

Por isso, recomenda-se monitorar os eventos recebidos e tratar falhas rapidamente.

👍

Retorno do Webhook com tipagem e ENUMs

Caso você queira saber qual o tipo de cada campo e os retornos de ENUMs disponíveis, confira a resposta 200 no endpoint "Recuperar uma única assinatura" na documentação.

🚧

Atenção

• Com a entrada de novos produtos e funções dentro do Asaas, é possível que novos atributos sejam incluídos no Webhook. É muito importante que seu código esteja preparado para não gerar exceções caso o Asaas devolva novos atributos não tratados pela sua aplicação, pois isso poderá causar interrupção na fila de sincronização.

  • Enviaremos um e-mail e avisaremos em nosso Discord quando novos campos forem incluídos no Webhook. O disparo será feito para o e-mail de notificação definido nas configurações do webhook.
  • O array de split será devolvido apenas quando a assinatura possuir configurações de Split de Pagamento.

Conteúdos relacionados

• Eventos de Webhooks;
• Receba eventos do Asaas no seu endpoint de Webhook;
• Como implementar idempotência em Webhooks;
• Logs de Webhooks;
• Penalização de filas;
• Fila pausada;
• Split de Pagamentos.