Events for API keys

With these events, you can be notified in real time whenever an API key is created, enabled, disabled, or deleted, even if the action is performed directly through the web interface. This is especially useful for parent accounts managing subaccounts and needing to ensure the integrity of their integrations.

How to use

To receive these events, you must have a Webhook configured in your account. Events related to API keys will be sent to the configured URL whenever a change occurs to a key.

We recommend:

• validating the origin of requests using an authToken;
• responding with HTTP 200 after persisting the received event;
• implementing idempotency using the event id;
• preparing your application to accept new attributes without generating exceptions.

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

Available events

The events notified by Asaas are:

• ACCESS_TOKEN_CREATED - New API key created.
• ACCESS_TOKEN_ENABLED - A previously disabled API key has been re-enabled.
• ACCESS_TOKEN_DISABLED - An API key has been disabled, either manually or by the automatic lifecycle process.
• ACCESS_TOKEN_DELETED - An API key has been permanently removed.
• ACCESS_TOKEN_EXPIRING_SOON - An API key will expire soon due to inactivity. This event is not triggered for keys with a manually defined expiration date.
• ACCESS_TOKEN_EXPIRED - An API key has permanently expired due to inactivity or manual configuration.

Example JSON received [POST]

The notification consists of a POST request containing a JSON payload, as shown below:

{
  "id": "evt_6561b631fa5580caadd00bbe3b858607&9193",
  "event": "ACCESS_TOKEN_CREATED",
  "dateCreated": "2024-10-16 11:11:04",
  "account": {
    "id": "47ed0d25-f9fb-4b35-b23a-d8895caf92b7",
    "ownerId": null
  },
  "accessToken": {
    "id": "cf7662a4-a7dd-40ec-b8de-d28617729501",
    "name": "TEST key",
    "enabled": false,
    "dateCreated": "2026-05-19 12:25:15",
    "disableReason": "MANUAL",
    "expirationDate": null,
    "projectedExpirationDateByLackOfUse": null
  }
}

Important fields

The most relevant fields for processing the event are:

• id: unique identifier of the event. Can be used to implement idempotency.
• event: type of event received.
• accessToken.id: identifier of the API key.
• accessToken.enabled: indicates whether the key is enabled.
• accessToken.disableReason: reason why the key was disabled.
• accessToken.expirationDate: manually configured expiration date.
• accessToken.projectedExpirationDateByLackOfUse: projected expiration date due to inactivity.

Possible values for disableReason

Best practices

• Respond with HTTP 200 after persisting the event.
• Use the event identifier (id) to prevent duplicate processing.
• Prepare your application to handle new fields in the payload.
• Monitor processing failures and implement logging.
• Use an authToken to validate the origin of requests.

🚧

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 yet handled by your application, as this may interrupt the synchronization queue.
• We will send an email and announce on our Discord whenever new fields are added to the Webhook. Notifications will be sent to the notification email configured in the Webhook settings.

Related content

• Receive Asaas events on your Webhook endpoint;
• Create a new Webhook through the web application;
• Create a new Webhook through the API;
• How to implement idempotency in Webhooks;
• Webhook Logs;
• Paused queue;
• Official Asaas IP addresses.