Webhooks Guide

Check the Webhooks guide for more information.

This endpoint allows you to list all webhooks registered in the authenticated account.

Listing webhooks is useful to identify existing configurations, locate the identifier of a specific webhook, and validate information before performing operations such as updating or removing a webhook.

When to use

This endpoint is recommended when:

• it is necessary to retrieve the webhooks configured in the account;
• you need to locate the identifier (id) of a webhook;
• existing configurations need to be validated;
• a webhook will be updated or removed;
• you want to audit the webhooks configured in the integration.

Dependencies for use

Before using this endpoint, it is necessary to:

• have an active Asaas account;
• have valid API authentication;
• have permission to access the account webhooks.

Without these conditions, the request cannot be performed.

Parameters used

📘

Important

It is recommended to use pagination when querying a large number of webhooks.

Operation behavior

When executing the request:

Retrieve webhooks
↓
API locates account records
↓
List of webhooks is returned
↓
Integration uses the data for retrieval, update, or removal

The response will only return webhooks belonging to the authenticated account.

The returned records contain the identifier (id) required for subsequent operations.

Request example

GET /v3/webhooks?offset=0&limit=10

Example:

GET /v3/webhooks?offset=0&limit=50

Usage example

A common flow consists of:

Retrieve webhooks
↓
Locate the webhook ID
↓
Select the desired webhook
↓
Update or remove the resource

Best practices

• Use pagination when dealing with large numbers of records.
• Internally store the identifiers of the most important webhooks.
• Retrieve webhooks before making configuration changes.
• Avoid creating multiple redundant webhooks for the same events.
• Periodically review the configured URLs.

Common errors

GET request with a body

GET requests must have an empty body.

When a body is sent, the API may return a 403 error.

Invalid token

This may occur when API authentication is invalid.

Incorrect pagination

This may occur when inconsistent values are used for offset or limit.

Limit exceeded

The limit parameter accepts a maximum of 100 records per request.

Operational impacts

For accounts with many registered webhooks, it is recommended to use pagination to avoid excessive queries.

Additionally, periodic retrieval of webhooks can be used for auditing and validating integration settings.

Next steps

Depending on the integration flow, the following contents may complement the implementation:

• Create webhook;
• Retrieve webhook;
• Update webhook;
• Remove webhook;
• Process webhook events.