Webhooks Guide

Check the Webhooks guide for more information.

This endpoint allows you to retrieve the settings of a specific webhook through its unique identifier (id).

This query is useful to validate webhook information, identify monitored events, verify whether it is active, and obtain data required for subsequent operations.

When to use

This endpoint is recommended when:

• it is necessary to retrieve a specific webhook;
• you want to validate its current settings;
• the webhook will be updated or removed;
• it is necessary to verify whether the webhook is active;
• you want to audit the settings of an existing integration.

Dependencies for use

Before performing the request, it is necessary to:

• have an active Asaas account;
• have valid API authentication;
• have the webhook identifier (id);
• ensure that the webhook belongs to the authenticated account.

Without these conditions, the request cannot be performed.

Parameters used

📘

Important

The id parameter corresponds to the webhook identifier and not to the configured URL or monitored events.

Operation behavior

When executing the request:

Existing webhook
↓
Retrieve by ID
↓
API locates the resource
↓
Webhook data is returned
↓
Integration uses the information

The response contains the current webhook settings, including monitored events and information required to manage the resource.

Request example

GET /v3/webhooks/wh_123456789

Example:

GET /v3/webhooks/wh_000001

Usage example

A typical integration follows the flow below:

List webhooks
↓
Locate the desired ID
↓
Retrieve specific webhook
↓
Validate settings
↓
Update or remove the resource

Best practices

• Store the webhook identifier after creation.
• Retrieve the resource before making changes.
• Use logs to audit configurations.
• Avoid maintaining multiple redundant webhooks for the same events.
• Periodically review configured URLs and events.

Common errors

Webhook not found

Occurs when the provided identifier does not exist or does not belong to the authenticated account.

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 or has expired.

Incorrect identifier

This may occur when an ID that does not exist or belongs to another resource is used.

Operational impacts

Retrieving a webhook allows you to validate configurations and reduce the risk of incorrect changes.

It is recommended to always retrieve the resource before updating or removing it, ensuring that the operation is performed on the correct webhook.

Next steps

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

• Create webhook;
• List webhooks;
• Update webhook;
• Remove webhook;
• Process webhook events.