Eventos para Pix Automático

É possível utilizar webhook para que seu sistema seja notificado sobre alterações que ocorram nas instruções e autorizações do Pix Automático. Os eventos que o Asaas notifica são:

• PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED - Elegibilidade da conta atualizada (para operações com subcontas).
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED - Autorização criada.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED - Autorização ativa.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED - Autorização cancelada.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED - Autorização expirada por falta de pagamento.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSED - Autorização recusada pelo banco.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED - Instrução de pagamento criada.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED - Instrução de pagamento agendada.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED - Instrução de pagamento recusada.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED - Instrução de pagamento cancelada.

Como utilizar

Para receber estes eventos, é necessário possuir um webhook configurado em sua conta.

Recomendamos:

• utilizar um authToken para validar a origem das requisições;
• responder rapidamente com HTTP 200 após persistir o evento;
• implementar idempotência utilizando o identificador do evento (id);
• preparar a aplicação para receber novos atributos sem gerar exceções.

Os Webhooks do Asaas seguem a premissa at least once, portanto um mesmo evento pode ser reenviado em situações excepcionais.

Exemplo de JSON a ser recebido [POST]

A notificação consiste em um POST contendo um JSON, conforme os exemplos:

Elegibilidade da conta

Essa mesma estrutura de payload é utilizada para o evento PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED, existindo dois tipos de eligibility.status: ELIGIBLE e INELIGIBLE.

📘

Importante

Se uma conta que era elegível (ELIGIBLE) se tornar inelegível (INELIGIBLE) e posteriormente voltar a ser ELIGIBLE, não é necessário reconfigurar os eventos de webhook do Pix Automático. Os eventos voltarão a ser enviados normalmente.

{
  "id": "evt_ID",
  "event": "PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED",
  "dateCreated": "2026-03-05 08:24:11",
  "account": {
    "id": "accountId",
    "ownerId": null
  },
  "eligibility": {
    "status": "INELIGIBLE",
    "ineligibleReasons": []
  }
}

📘

Campo ineligibleReasons

O array ineligibleReasons contém a lista de motivos pelos quais a conta está inelegível.

Autorização

Nestes eventos, o payload é o mesmo e o que varia é o campo authorization.status, que pode assumir os valores:

• CREATED
• ACTIVE
• CANCELLED
• EXPIRED
• REFUSED

{
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED",
  "authorization": {
    "id": "d51008fa-e28e-4823-82b4-4b1fcf485229",
    "status": "ACTIVE",
    "customerId": "cus_000006869125",
    "frequency": "MONTHLY",
    "value": 2.00,
    "startDate": "2025-08-01",
    "finishDate": "2028-01-01",
    "immediateQrCode": {
      "conciliationIdentifier": "ASAAS000000000000000000000000550ASA",
      "expirationDate": "2025-07-24 18:00:20"
    }
  }
}

Instrução de pagamento

Nestes eventos, o payload é o mesmo e o campo paymentInstruction.status pode assumir os valores:

• AWAITING_REQUEST
• SCHEDULED
• REFUSED
• CANCELLED

{
  "event": "PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED",
  "paymentInstruction": {
    "id": "f6559451-cb41-4ec6-8487-2cda59a5f184",
    "status": "SCHEDULED",
    "dueDate": "2024-10-04",
    "payment": "pay_080225913252",
    "authorization": {
      "id": "c6b180f0-2196-454c-ac7e-72d662286bd1"
    }
  }
}

Campos importantes

Evento

• id: identificador único do evento. Deve ser utilizado para idempotência.
• event: tipo do evento recebido.
• dateCreated: data da geração do evento.

Elegibilidade

• eligibility.status: situação atual da elegibilidade da conta.
• eligibility.ineligibleReasons: lista de motivos da inelegibilidade.

Autorizações

• authorization.id: identificador da autorização.
• authorization.status: estado atual da autorização.
• authorization.customerId: cliente associado.
• authorization.frequency: periodicidade.
• authorization.value: valor da recorrência.

Instruções de pagamento

• paymentInstruction.id: identificador da instrução.
• paymentInstruction.status: estado atual da instrução.
• paymentInstruction.payment: cobrança relacionada.
• paymentInstruction.authorization.id: autorização associada.

Comportamentos importantes

• Os eventos são entregues seguindo a premissa at least once.
• Um mesmo evento poderá ser reenviado em caso de falha.
• Recomenda-se implementar idempotência utilizando o campo id.
• O endpoint deve responder com HTTP 200 o mais rapidamente possível.
• Novos atributos podem ser adicionados ao payload sem aviso prévio.
• O processamento assíncrono é recomendado para evitar interrupções na fila.

Boas práticas

• Persistir o evento antes do processamento.
• Implementar logs e monitoramento.
• Validar a origem da requisição utilizando um authToken.
• Ignorar campos desconhecidos.
• Processar os eventos de forma assíncrona.
• Utilizar o identificador do evento para evitar processamentos duplicados.

🚧

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.

Impacto operacional

Caso o endpoint não esteja disponível ou retorne erros, os eventos poderão ser reenviados. A ausência de idempotência poderá provocar processamento duplicado de autorizações ou instruções de pagamento.

Por isso, recomenda-se monitorar continuamente os Webhooks e manter alta disponibilidade do endpoint.

Conteúdos relacionados

• Receba eventos do Asaas no seu endpoint de Webhook;
• Como implementar idempotência em Webhooks;
• Eventos de Webhooks;
• Logs de Webhooks;
• Fila pausada;
• IPs oficiais do Asaas;
• Pix Automático.