Anticipation events

Listen to Asaas events to keep your integration up to date.

Use anticipation events to automatically track the state changes of a receivables anticipation.

Each notification indicates the event that occurred in event and the current operation data in the anticipation object.

Available events

Event	When it occurs
`RECEIVABLE_ANTICIPATION_CANCELLED`	The anticipation is cancelled.
`RECEIVABLE_ANTICIPATION_SCHEDULED`	The anticipation is scheduled.
`RECEIVABLE_ANTICIPATION_PENDING`	The anticipation is under review.
`RECEIVABLE_ANTICIPATION_CREDITED`	The anticipation is credited.
`RECEIVABLE_ANTICIPATION_DEBITED`	The anticipation is debited.
`RECEIVABLE_ANTICIPATION_DENIED`	The anticipation request is denied.
`RECEIVABLE_ANTICIPATION_OVERDUE`	The anticipation becomes overdue.

The events represent changes in the anticipation processing. Do not assume that every operation will go through all the events above or that they form a mandatory sequence.

How to interpret the events

Event	Handling in the integration
`RECEIVABLE_ANTICIPATION_SCHEDULED`	Keep the operation as scheduled.
`RECEIVABLE_ANTICIPATION_PENDING`	Indicate that the anticipation is under review.
`RECEIVABLE_ANTICIPATION_CREDITED`	Confirm the anticipation credit in your system.
`RECEIVABLE_ANTICIPATION_DEBITED`	Update the operation to reflect the debit.
`RECEIVABLE_ANTICIPATION_DENIED`	Mark the request as denied and check `anticipation.denialObservation`, when filled in.
`RECEIVABLE_ANTICIPATION_CANCELLED`	Update the operation as cancelled.
`RECEIVABLE_ANTICIPATION_OVERDUE`	Update the operation to reflect that it is overdue.

event identifies the change notified by the Webhook. anticipation.status represents the current status of the anticipation in the payload.

Event payload

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

{
  "id": "evt_05b708f961d739ea7eba7e4db318f621&368604920",
  "event": "RECEIVABLE_ANTICIPATION_CREDITED",
  "dateCreated": "2024-06-12 16:45:03",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "anticipation": {
    "object": "anticipation",
    "id": "29ad50e9-64ee-427e-a00c-a3999510ca0a",
    "installment": null,
    "payment": "pay_4310966350068380",
    "status": "CREDITED",
    "anticipationDate": "2022-09-19",
    "dueDate": "2022-09-30",
    "requestDate": "2022-09-19",
    "fee": 5.64,
    "anticipationDays": 11,
    "netValue": 302.37,
    "totalValue": 310,
    "value": 308.01,
    "denialObservation": null
  }
}

Important payload fields

Field	Description
`id`	Unique identifier of the event. Use it for idempotence.
`event`	Identifies the event received.
`anticipation.id`	Anticipation identifier.
`anticipation.status`	Current status of the anticipation.
`anticipation.payment`	Charge related to the anticipation, when applicable.
`anticipation.installment`	Installment related to the anticipation, when applicable.
`anticipation.netValue`	Net amount credited.
`anticipation.totalValue`	Gross amount of the anticipation.
`anticipation.fee`	Fee applied.
`anticipation.denialObservation`	Reason for the denial, when there is one.

👍
Webhook response with types and ENUMs
If you want to know the type of each field and the available ENUM values, check the 200 response of the "Retrieve a single anticipation" endpoint in the documentation.

How to handle the events

When receiving an anticipation event:

identify the change through the event field;
persist the id to prevent duplicate processing;
use anticipation.id to find the anticipation in your system;
update the operation according to the event and anticipation.status;
respond HTTP 200 after confirming persistence;
process additional rules asynchronously.

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

See how to implement idempotence in Webhooks.

To track the anticipation's state changes, prefer these events instead of periodically querying the API. Use the individual query only when you need to retrieve the current state of an operation on a one-off basis.

🚧
Attention

As new products and features are added to Asaas, new attributes may be included in the Webhook. It is very important that your code is prepared not to throw exceptions if Asaas returns new attributes that your application does not handle, as this may interrupt the sync queue.

We will send an email and announce on our Discord when new fields are added to the Webhook. The email will be sent to the notification email address defined in the Webhook settings.

Next steps

Updated 10 days ago

Did this page help you?