Events for invoices

It is possible to use Webhooks so that your system is notified about changes that occur in invoices.

Invoice events allow you to track the entire issuance, synchronization, authorization, cancellation, and failure handling cycle of invoices issued through Asaas.

The events that Asaas notifies are:

• INVOICE_CREATED - New invoice created.
• INVOICE_UPDATED - Invoice updated.
• INVOICE_SYNCHRONIZED - Invoice sent to the city hall.
• INVOICE_AUTHORIZED - Invoice issued.
• INVOICE_PROCESSING_CANCELLATION - Invoice cancellation being processed.
• INVOICE_CANCELED - Invoice canceled.
• INVOICE_CANCELLATION_DENIED - Invoice cancellation denied.
• INVOICE_ERROR - Invoice with error.

When to use

Invoice Webhooks are recommended when your application needs to automatically track the status of invoices issued by Asaas.

Some use examples:

• make the invoice PDF available to the customer;
• store the invoice XML in external systems;
• track authorizations and cancellations;
• update an ERP or proprietary system;
• identify issuance errors;
• execute automated tax integrations.

Event flow

The lifecycle of an invoice usually follows this flow:

Invoice created
↓
INVOICE_CREATED
↓
Sent to city hall
↓
INVOICE_SYNCHRONIZED
↓
Invoice authorized
↓
INVOICE_AUTHORIZED

If any change occurs:

Invoice updated
↓
INVOICE_UPDATED

In case of cancellation:

Cancellation request
↓
INVOICE_PROCESSING_CANCELLATION
↓
INVOICE_CANCELED

If the city hall denies the cancellation:

INVOICE_CANCELLATION_DENIED

In case of error:

INVOICE_ERROR

Example JSON to be received [POST]

The notification consists of a POST containing a JSON, as shown in this example:

{
    "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 amount referring to work performed 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

📘

Important

The pdfUrl, xmlUrl, number, and validationCode fields are usually filled after the invoice is authorized.

Important behaviors

Webhooks follow the at least once delivery model.

This means that the same event may be sent more than once.

For this reason, it is recommended to implement idempotency using the event field:

id

In addition:

• events may be resent in case of failure;
• the endpoint must return an HTTP status code in the 2xx range;
• different responses may trigger new delivery attempts;
• the queue may be interrupted after consecutive failures;
• events remain stored for up to 14 days;
• new attributes may be added to the payload in the future.

Security

It is recommended to validate the header:

asaas-access-token

using the token configured in the Webhook.

It is also recommended to allow requests only from the official Asaas IPs.

Best practices

• Process events asynchronously.
• Respond quickly with HTTP 2xx.
• Use the event id field to implement idempotency.
• Use invoice.id as the main invoice identifier.
• Do not rely on event delivery order.
• Monitor Webhook Logs.
• Prepare your application to receive new fields in the payload.

Common errors

INVOICE_ERROR

Indicates a failure in invoice issuance.

It is recommended to check the error details and review the account tax configuration.

Duplicate event

Since delivery follows the "at least once" model, the same event may be resent.

Use the event identifier to avoid reprocessing.

Endpoint returning an error

If the application returns responses outside the 2xx range, new attempts may occur.

PDF or XML unavailable

The pdfUrl and xmlUrl fields will only be filled after the invoice is authorized.

Operational impacts

Invoice events can be used for synchronization with ERPs, CRMs, and tax systems.

Processing failures may cause:

• tax divergences between systems;
• unavailability of the PDF or XML for customers;
• loss of synchronization with external systems;
• duplicate processing;
• interruption of the Webhook queue.

For this reason, continuous monitoring of the integration is recommended.

👍

Webhook return with typing and ENUMs

If you want to know the type of each field and the available ENUM returns, check the 200 response in the endpoint "Retrieve an invoice" in the documentation.

🚧

Attention

• With the introduction of new products and features in Asaas, new attributes may be added to the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes not handled by your application, as this may cause interruption of the synchronization queue.
• We will send an email and notify on our Discord when new fields are added to the Webhook. The notification will be sent to the notification email defined in the Webhook settings.

Related content

• Webhook Events;
• Receive events from Asaas on your Webhook endpoint;
• How to implement idempotency in Webhooks;
• Webhook Logs;
• Paused queue;
• Queue penalties;
• Invoices.