States, events, and consistency

Operations can change state after the initial API response.

That is why your application must track the lifecycle of entities and keep local data aligned with Asaas through states, events, and reconciliation mechanisms.

When to use

Consider this model when:

• implementing operations whose status may change after creation;
• using Webhooks to update your application;
• executing actions that depend on the current state of an entity;
• handling duplicate, delayed, or out-of-sequence events;
• identifying and fixing mismatches between the local state and Asaas.

Before you start

Before defining this flow:

• identify which entities your application needs to track;
• map the relevant states of each entity;
• define which states allow an operation to advance, stop, or be repeated;
• keep the Asaas ID linked to the corresponding identifier in your system;
• define how your application will receive updates and how mismatches will be reconciled.

How it works

Consistency depends on three mechanisms working together:

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Operation in Asaas"] --> B["Current state"]
    B --> C["Update event"]
    C --> D["Process event"]
    D --> E["Update local state"]
    E --> F{"Is the local state consistent?"}

    F --> FSim(("Yes"))
    F --> FNao(("No"))

    FSim --> G["Continue the flow"]
    FNao --> H["Reconcile with Asaas"]
    H --> E

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef processo fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef recuperacao fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px,font-size:17px

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

    class A inicio
    class B,C,D,E processo
    class F decisao
    class G sucesso
    class H recuperacao

    class FSim respostaSim
    class FNao respostaNao

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

Events keep your application up to date during the normal flow. Reconciliation works as an additional layer to fix situations in which the local state no longer reflects the current state in Asaas.

1. Model the entity states

The state represents the current situation of an entity at a given moment.

Charges, subscriptions, transfers, and other entities can go through different stages during their lifecycle. That is why storing only the status returned at creation time is not enough.

For each entity used by the integration, identify:

• which states can occur;
• which represent the start of the flow;
• which are intermediate;
• which represent a final condition;
• which require some action from the application;
• which allow moving on to a next step;
• which may still change later.

The status must be part of the integration logic, not treated merely as text stored in the database.

2. Link the local state to the record in Asaas

Your application must be able to unambiguously identify which local record corresponds to the entity in Asaas.

Keep, at a minimum:

• the ID returned by Asaas;
• your application's internal identifier;
• the currently known state;
• the date of the last update;
• the source of the update;
• enough information to trace later changes.

This relationship makes it possible to process events, run queries, and investigate mismatches without relying on imprecise searches.

3. Process events as state changes

Events report relevant changes that occurred during the entity's lifecycle.

In asynchronous flows, they allow your application to keep tracking the operation after the initial API response.

When processing an event:

1. identify the related entity;
2. retrieve the currently stored state;
3. evaluate the information received;
4. apply the necessary update;
5. record the change;
6. execute actions that depend on this new state only after the update.

Processing must not depend on the assumption that each event will be received only once or exactly in the expected sequence.

4. Account for duplicate and delayed events

Your architecture must tolerate different delivery conditions.

An event may:

• be received more than once;
• arrive after another related event;
• be processed with a delay;
• fail during processing;
• arrive when your application already has more recent information.

That is why, before updating an entity or executing an action, consider the current recorded state and the actual effect of that update.

Avoid implementing rules based exclusively on the order in which events were received.

5. Validate transitions before executing actions

Not every state change should automatically produce a new operation.

Before advancing a flow, validate whether the current state allows that action.

For example, before:

• releasing a product or service;
• executing a new attempt;
• canceling an operation;
• starting a transfer;
• updating a financial situation as completed;

confirm that the known state is compatible with that decision.

This control reduces the risk of a delayed or duplicate update triggering an incorrect action.

6. Keep the local state consistent

An integration is consistent when the information used by your application correctly represents the current situation of the operation in Asaas.

When this does not happen, you may see:

• mismatched statuses;
• decisions based on outdated information;
• unnecessary reprocessing;
• duplicate operations;
• manual interventions;
• difficulty identifying the source of the problem.

For example, a charge may be confirmed in Asaas while your application keeps treating the record as pending if the corresponding update is not processed.

In this situation, the problem is not necessarily in the financial operation, but in the difference between the state kept in the two systems.

7. Implement reconciliation

Even when using Webhooks, your application must be prepared to identify and fix mismatches.

Reconciliation works as a complementary layer to normal event processing.

A basic routine can:

1. identify pending, old, or inconsistent records;
2. query the current state of the entity in Asaas;
3. compare the response with the local record;
4. fix the mismatch when necessary;
5. record the change made;
6. analyze recurring occurrences to identify structural problems.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart LR
    A["Select operations for validation"] --> B["Query state in Asaas"]
    B --> C["Compare with local state"]
    C --> D{"Is there a mismatch?"}
    D -- "No" --> E["Keep record"]
    D -- "Yes" --> F["Update local state"]
    F --> G["Record correction"]
    G --> H["Evaluate the cause of the mismatch"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef processo fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef recuperacao fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px,font-size:17px

    class A inicio
    class B,C processo
    class D decisao
    class E sucesso
    class F,G,H recuperacao

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

Reconciliation does not replace Webhooks. Its goal is to recover inconsistencies that were not fixed by the normal flow.

Attention — common mistakes

Avoid architectures that:

• store only the initial status of the entity;
• treat the status only as visual information;
• assume events always arrive in the expected order;
• execute actions without validating the current state;
• reprocess a duplicate event as if it were new;
• depend exclusively on Webhooks to maintain consistency;
• do not record enough information to trace changes;
• repeat an operation without checking whether it has already been completed.

Confirm your architecture

Before go-live, confirm that your application can answer:

• Which states can each entity take?
• Which states are initial, intermediate, or final?
• Which states allow an operation to advance?
• Which require handling or intervention?
• How will the local state be updated?
• How will duplicate events be identified?
• How will delayed events be handled?
• Does processing depend on the order in which events are received?
• How will mismatches be identified?
• When can an operation be executed again?
• How can a state change be traced later?

If these definitions do not exist, your application may make decisions based on incomplete or outdated information.

Best practices

• treat states as part of the integration's business logic;
• keep the Asaas ID linked to the internal identifier;
• record when and how each state was updated;
• design event processing to tolerate duplicates;
• do not depend on a strict event delivery order;
• validate the current state before executing critical actions;
• keep enough history for diagnosis;
• use reconciliation as a complementary layer to Webhooks.

Next steps

Now that your application can control state changes and fix mismatches, understand when to rely on an immediate response and when to wait for later updates:

• Synchronous and asynchronous communication
• Webhooks and events