Invoice events

Use invoice events to track the issuance, update, authorization, cancellation and failures of invoices issued by Asaas.

Each notification contains the event type in event and the invoice data in the invoice object.

Available events

Issuance flow

The usual issuance flow goes through creation, synchronization with the city hall and authorization of the invoice.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["INVOICE_CREATED"] --> B["Send to the city hall"]
    B --> C["INVOICE_SYNCHRONIZED"]
    C --> D["Process authorization"]
    D --> E["INVOICE_AUTHORIZED"]

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

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

The INVOICE_UPDATED event may occur when the invoice data is changed.

Cancellation flow

When cancellation is requested, track the result through the event sent after processing.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Request cancellation"] --> B["INVOICE_PROCESSING_<br/>CANCELLATION"]
    B --> C{"Cancellation authorized?"}

    C --> CSim(("Yes"))
    C --> CNao(("No"))

    CSim --> D["INVOICE_CANCELED"]
    CNao --> E["INVOICE_CANCELLATION_<br/>DENIED"]

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

    class CSim respostaSim
    class CNao,E respostaNao

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

If a failure related to the invoice occurs, INVOICE_ERROR will be sent.

Event payload

The notification is sent via POST with the event and the invoice data.

{
    "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
    "event": "INVOICE_CREATED",
    "dateCreated": "2024-06-12 16:45:03",
    "account": {
        "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
        "ownerId": null
    },
    "invoice": {
        "object": "invoice",
        "id": "inv_000000000232",
        "status": "SCHEDULED",
        "customer": "cus_000000002750",
        "type": "NFS-e",
        "statusDescription": null,
        "serviceDescription": "Invoice for Bill 101940. \nService Description: SYSTEMS ANALYSIS AND DEVELOPMENT",
        "pdfUrl": null,
        "xmlUrl": null,
        "rpsSerie": null,
        "rpsNumber": null,
        "number": null,
        "validationCode": null,
        "value": 300,
        "deductions": 0,
        "effectiveDate": "2018-07-03",
        "observations": "Monthly fee for the work done in June.",
        "estimatedTaxesDescription": "",
        "payment": "pay_145059895800",
        "installment": null,
        "taxes": {
            "retainIss": false,
            "iss": 3,
            "cofins": 3,
            "csll": 1,
            "inss": 0,
            "ir": 1.5,
            "pis": 0.65
        },
        "municipalServiceCode": "1.01",
        "municipalServiceName": "Systems analysis and development"
    }
}

Important payload fields

How to handle the events

When receiving an invoice event:

1. identify the change through the event field;
2. persist the id to prevent duplicate processing;
3. use invoice.id to identify the invoice;
4. respond HTTP 200 after confirming persistence;
5. process the update in your system.

Webhooks follow the at least once model, so the same event may be sent more than once.

See how to implement idempotence in Webhooks.

How to handle specific events

INVOICE_AUTHORIZED

When the invoice is authorized, use the data in the invoice object to update your system and, when available, store or make available pdfUrl, xmlUrl, number and validationCode.

INVOICE_ERROR

The event indicates a failure related to the invoice.

Check the data returned in the event and the tax configuration used for issuance before retrying or intervening.

INVOICE_CANCELLATION_DENIED

The cancellation was not authorized. Keep the invoice in sync with the state returned by Asaas and handle the denial according to your integration's rules.

Validate the Webhook origin

When using authToken, validate the header:

asaas-access-token

If your infrastructure restricts requests by origin, see the Asaas official IPs.

Next steps

• Receive Asaas events at your Webhook endpoint
• Implement idempotence in Webhooks
• Monitor the Webhook Logs
• See the other Webhook Events
• Learn about the Invoices flow