Tipos de envio

O tipo de envio define se o Asaas deve preservar a ordem dos eventos ou permitir entregas em paralelo.

Escolha essa configuração de acordo com a dependência entre os eventos processados pela sua aplicação.

Compare os tipos de envio

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Definir a lógica do Webhook"] --> B{"A ordem dos eventos é necessária?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Usar SEQUENTIALLY"]
    BNao --> D["Usar NON_SEQUENTIALLY"]

    C --> E["Configurar o Webhook"]
    D --> E

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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
    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

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

    class BSim respostaSim
    class BNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

Envio Sequencial

Use SEQUENTIALLY quando a aplicação precisar receber os eventos na ordem em que ocorreram.

Esse comportamento é adequado para jornadas em que um evento depende do estado produzido pelo evento anterior.

Exemplo em cobranças

Uma cobrança recebida após o vencimento pode gerar esta sequência:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_OVERDUE"]
    B --> C["PAYMENT_CONFIRMED"]
    C --> D["PAYMENT_RECEIVED"]

    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 validacao
    class D sucesso

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

Nesse cenário, preservar a ordem permite identificar que o pagamento ocorreu depois do vencimento.

No envio Sequencial, um evento lento ou com falha pode atrasar os eventos seguintes. Utilize esse tipo quando a preservação da ordem for necessária para a lógica da aplicação.

Envio Não Sequencial

Use NON_SEQUENTIALLY quando os eventos puderem ser tratados independentemente da ordem em que forem recebidos.

Nesse modo, o Asaas não precisa aguardar a conclusão dos eventos anteriores para realizar novos envios. As notificações podem ser entregues simultaneamente e chegar fora da ordem em que ocorreram.

Esse comportamento é indicado para integrações com alto volume, processamento paralelo ou eventos que não dependem do estado produzido por notificações anteriores.

Se utilizar esse tipo de envio, não baseie a regra de negócio na ordem de chegada das requisições.

Comportamento comum aos dois tipos

Independentemente do sendType, os Webhooks seguem o modelo at least once. O mesmo evento pode ser enviado mais de uma vez, mantendo o mesmo id.

Sua aplicação deve:

1. persistir o evento utilizando id como identificador único;
2. responder HTTP 200 após confirmar a persistência;
3. processar a regra de negócio de forma assíncrona.

A idempotência é necessária tanto no envio Sequencial quanto no Não Sequencial. O envio Sequencial preserva a ordem de entrega, mas não impede reenvios.

Consulte como implementar idempotência em Webhooks.

Próximos passos

• Crie um Webhook pela aplicação web
• Crie um Webhook pela API
• Escolha os Eventos de Webhooks
• Receba eventos do Asaas no seu endpoint de Webhook
• Implemente idempotência em Webhooks
• Monitore os Logs de Webhooks