Fluxos de Webhook do Pix Automático

Acompanhe os eventos do Pix Automático por Webhook

Os Webhooks do Pix Automático permitem acompanhar alterações de status das autorizações, instruções de pagamento e cobranças recorrentes sem depender de consultas constantes à API.

📘
Ao concluir este guia, você saberá interpretar os principais eventos do Pix Automático e acompanhar o ciclo de vida das autorizações e instruções de pagamento.

Quando utilizar

Utilize os Webhooks para:

acompanhar ativações, recusas, cancelamentos e expirações de autorizações;
acompanhar a criação e o processamento das instruções de pagamento;
atualizar o status das cobranças recorrentes;
executar ações internas conforme os eventos recebidos.

Antes de começar

Os eventos relacionados às cobranças recorrentes dependem de uma autorização válida.

O fluxo normalmente ocorre nesta ordem:

criar a autorização;
ativar a autorização;
criar as cobranças;
enviar as instruções de pagamento ao banco pagador.

📘
Sem uma autorização ativa, novos agendamentos não poderão ser processados.
O cancelamento ou a expiração da autorização também pode provocar o cancelamento das instruções de pagamento relacionadas.

Estrutura dos eventos

Os Webhooks do Pix Automático seguem o mesmo padrão dos demais Webhooks do Asaas.

Os principais campos para correlacionar os eventos com os registros da aplicação são:

Campo	Finalidade
`event`	Identifica o evento recebido
`id`	Identificador do recurso relacionado
`dateCreated`	Data de geração do evento
`payment`	Identificador da cobrança, quando aplicável
`pixAutomaticAuthorization`	Identificador da autorização do Pix Automático

Exemplo:

{
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED",
  "id": "evt_123456",
  "dateCreated": "2026-07-13 14:32:18",
  "pixAutomaticAuthorization": "aut_987654",
  "payment": "pay_123456"
}

👍
Recomendado
Utilize os identificadores retornados no payload para correlacionar os eventos com sua base de dados. Não dependa da ordem de recebimento dos Webhooks.

Boas práticas

Considere os Webhooks como assíncronos.
Processe os eventos de forma idempotente.
Utilize o identificador do evento para evitar processamento duplicado.
Responda HTTP 200 após processar o evento.
Implemente reprocessamento seguro.
Mantenha o endpoint disponível para novas tentativas de entrega.
Consulte a API quando precisar confirmar o estado mais recente do recurso.

⚠️
Atenção
Um mesmo evento pode ser reenviado em caso de falha na entrega.
Eventos diferentes também podem ser recebidos em momentos distintos.

Eventos de pagamento

O Pix Automático utiliza eventos financeiros já existentes na API do Asaas.

No pagamento do QR Code imediato, o recebimento é representado por:

PAYMENT_RECEIVED

Nos fluxos das cobranças recorrentes, os eventos representam a evolução da instrução de pagamento e da cobrança.

Sempre considere o evento efetivamente recebido pela integração.

Fluxos das autorizações

As autorizações representam o consentimento concedido pelo pagador para permitir cobranças recorrentes.

Autorização concedida com sucesso

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED"] --> B["PAYMENT_CREATED"]
    B --> C["PAYMENT_RECEIVED"]
    C --> D["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C validacao
    class D sucesso

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

Após a ativação, novas cobranças recorrentes podem ser vinculadas à autorização.

Autorização expirada

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED"] --> B["PAYMENT_CREATED"]
    B --> C["PAYMENT_RECEIVED"]
    C --> D["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED"]
    D --> E["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C,D validacao
    class E analise

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

📘
Ao atingir a data configurada em finishDate, a autorização expira e novas cobranças não serão processadas.

QR Code expirado sem pagamento

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B analise

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

Nesse cenário, a autorização não é ativada.

Autorização cancelada

O fluxo é o mesmo para cancelamento realizado pelo pagador ou pelo cliente Asaas:

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED"] --> B["PAYMENT_CREATED"]
    B --> C["PAYMENT_RECEIVED"]
    C --> D["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED"]
    D --> E["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C,D validacao
    class E analise

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

Após o cancelamento, novas cobranças recorrentes deixam de ser processadas.

Fluxos das instruções de pagamento

As instruções de pagamento representam os agendamentos enviados ao banco pagador para execução das cobranças recorrentes.

Pagamento realizado com sucesso

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED"]
    C --> D["PAYMENT_CONFIRMED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C validacao
    class D sucesso

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

Falha por saldo ou limite insuficiente

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED"]
    C --> D["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C validacao
    class D analise

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

Esse cenário pode ocorrer por falta de saldo ou limite disponível no banco pagador.

Recusa do agendamento

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B validacao
    class C analise

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

Falhas operacionais podem impedir o agendamento da instrução.

Instrução cancelada

O fluxo é o mesmo para cancelamento realizado pelo pagador ou pelo cliente Asaas:

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED"]
    C --> D["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C validacao
    class D analise

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

Cobrança paga por outro meio

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED"]
    C --> D["PAYMENT_CONFIRMED"]
    D --> E["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

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

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

📘
Se a cobrança for recebida por outro meio, a instrução automática é cancelada para evitar uma nova execução.

Autorização cancelada com instrução agendada

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED"]
    B --> C["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED"]
    C --> D["PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED"]
    D --> E["PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px
    classDef correcao fill:#FFEDD5,stroke:#EA580C,color:#7C2D12,stroke-width:2px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
    classDef analise fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:3px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px
    classDef respostaDuvida fill:#8B5CF6,stroke:#6D28D9,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,C validacao
    class D,E analise

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

Cuidados importantes

O cancelamento da autorização interrompe cobranças futuras.
A expiração da autorização impede novos agendamentos.
Uma instrução cancelada pode ser consequência de um pagamento realizado por outro meio.
Trate os eventos de forma assíncrona e idempotente.
Determine o estado da cobrança pelos eventos recebidos e pelo recurso relacionado, não apenas pela existência da instrução.

Próximos passos

Updated 8 days ago

Did this page help you?