Events for Automatic Pix

You can use Webhooks so that your system is notified whenever changes occur to Automatic Pix instructions and authorizations. The events notified by Asaas are:

• PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED - Account eligibility updated (for subaccount operations).
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CREATED - Authorization created.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED - Authorization activated.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_CANCELLED - Authorization cancelled.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_EXPIRED - Authorization expired due to lack of payment.
• PIX_AUTOMATIC_RECURRING_AUTHORIZATION_REFUSED - Authorization refused by the bank.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CREATED - Payment instruction created.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED - Payment instruction scheduled.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_REFUSED - Payment instruction refused.
• PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_CANCELLED - Payment instruction cancelled.

How to use

To receive these events, you must have a Webhook configured in your account.

We recommend:

• using an authToken to validate the origin of requests;
• responding quickly with HTTP 200 after persisting the event;
• implementing idempotency using the event identifier (id);
• preparing your application to accept new attributes without throwing exceptions.

Asaas Webhooks follow the at least once delivery model, so the same event may be resent in exceptional situations.

Example JSON received [POST]

Notifications are sent through POST requests containing a JSON payload, as shown below.

Account eligibility

The same payload structure is used for the PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED event. The eligibility.status field can have two possible values: ELIGIBLE and INELIGIBLE.

📘

Important

If an account that was previously eligible (ELIGIBLE) becomes ineligible (INELIGIBLE) and later returns to ELIGIBLE, it is not necessary to reconfigure the Automatic Pix Webhook events. Events will resume being sent normally.

{
  "id": "evt_ID",
  "event": "PIX_AUTOMATIC_RECURRING_ELIGIBILITY_UPDATED",
  "dateCreated": "2026-03-05 08:24:11",
  "account": {
    "id": "accountId",
    "ownerId": null
  },
  "eligibility": {
    "status": "INELIGIBLE",
    "ineligibleReasons": []
  }
}

📘

ineligibleReasons field

The ineligibleReasons array contains the list of reasons why the account is ineligible.

Authorization

For these events, the payload is the same. The authorization.status field may assume the following values:

• CREATED
• ACTIVE
• CANCELLED
• EXPIRED
• REFUSED

{
  "event": "PIX_AUTOMATIC_RECURRING_AUTHORIZATION_ACTIVATED",
  "authorization": {
    "id": "d51008fa-e28e-4823-82b4-4b1fcf485229",
    "status": "ACTIVE",
    "customerId": "cus_000006869125",
    "frequency": "MONTHLY",
    "value": 2.00,
    "startDate": "2025-08-01",
    "finishDate": "2028-01-01",
    "immediateQrCode": {
      "conciliationIdentifier": "ASAAS000000000000000000000000550ASA",
      "expirationDate": "2025-07-24 18:00:20"
    }
  }
}

Payment instruction

For these events, the payload is also the same. The paymentInstruction.status field may assume the following values:

• AWAITING_REQUEST
• SCHEDULED
• REFUSED
• CANCELLED

{
  "event": "PIX_AUTOMATIC_RECURRING_PAYMENT_INSTRUCTION_SCHEDULED",
  "paymentInstruction": {
    "id": "f6559451-cb41-4ec6-8487-2cda59a5f184",
    "status": "SCHEDULED",
    "dueDate": "2024-10-04",
    "payment": "pay_080225913252",
    "authorization": {
      "id": "c6b180f0-2196-454c-ac7e-72d662286bd1"
    }
  }
}

Important fields

Event

• id: unique identifier of the event. Must be used for idempotency.
• event: type of event received.
• dateCreated: event creation date.

Eligibility

• eligibility.status: current account eligibility status.
• eligibility.ineligibleReasons: list of reasons for ineligibility.

Authorizations

• authorization.id: authorization identifier.
• authorization.status: current authorization state.
• authorization.customerId: associated customer.
• authorization.frequency: recurrence frequency.
• authorization.value: recurring amount.

Payment instructions

• paymentInstruction.id: payment instruction identifier.
• paymentInstruction.status: current instruction state.
• paymentInstruction.payment: related payment.
• paymentInstruction.authorization.id: associated authorization.

Important behaviors

• Events are delivered following the at least once principle.
• The same event may be resent in case of failures.
• Idempotency should be implemented using the id field.
• The endpoint should respond with HTTP 200 as quickly as possible.
• New attributes may be added to the payload without prior notice.
• Asynchronous processing is recommended to avoid synchronization queue interruptions.

Best practices

• Persist the event before processing it.
• Implement logging and monitoring.
• Validate the request origin using an authToken.
• Ignore unknown fields.
• Process events asynchronously.
• Use the event identifier to prevent duplicate processing.

🚧

Attention

• As new products and features are introduced into Asaas, new attributes may be added to Webhooks. It is very important that your code is prepared not to throw exceptions when Asaas returns new attributes that are not handled by your application, as this may interrupt the synchronization queue.
• We will send an email and announce it on our Discord whenever new fields are added to the Webhook. Notifications will be sent to the email configured in the Webhook settings.

Operational impact

If the endpoint is unavailable or returns errors, events may be resent. The absence of idempotency may lead to duplicate processing of authorizations or payment instructions.

For this reason, we recommend continuously monitoring Webhooks and maintaining high endpoint availability.

Related content

• Receive Asaas events on your Webhook endpoint;
• How to implement idempotency in Webhooks;
• Webhook Events;
• Webhook Logs;
• Paused Queue;
• Official Asaas IP addresses;
• Automatic Pix.