Webhooks Guide

Check the Webhooks guide for more information.

This endpoint allows you to update the settings of an existing webhook.

The operation can be used to modify information such as the destination URL, monitored events, authentication token, delivery type, and webhook status.

When to use

This endpoint is recommended when:

• the destination URL of the webhook needs to be changed;
• new events need to be added or removed;
• you want to enable or disable the webhook;
• it is necessary to interrupt or reactivate the synchronization queue;
• the authToken needs to be replaced;
• operational adjustments need to be performed in an existing integration.

Dependencies for use

Before updating a webhook, 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 update cannot be performed.

Parameters used

📘

Important

If the authToken needs to be updated, it is recommended to follow the security requirements described in the webhook creation documentation.

The authToken must contain between 32 and 255 characters.

Operation behavior

When updating a webhook:

Existing webhook
↓
Settings are updated
↓
New information is persisted
↓
Future events will use the new configuration

Changes are applied only to future events.

Events that have already been processed are not affected by the update.

Request example

PUT /v3/webhooks/wh_123456789

{
  "name": "Payment webhook",
  "url": "https://www.yourapplication.com/webhooks/asaas",
  "enabled": true,
  "interrupted": false,
  "sendType": "SEQUENTIALLY",
  "authToken": "secure-token-with-more-than-32-characters",
  "events": [
    "PAYMENT_RECEIVED",
    "PAYMENT_OVERDUE"
  ]
}

Usage example

A common flow consists of:

Retrieve webhook
↓
Identify the need for changes
↓
Update settings
↓
Save changes
↓
Continue receiving events normally

Best practices

• Retrieve the webhook before making changes.
• Use a strong authToken.
• Update only the required events.
• Keep the destination URL available to receive notifications.
• Internally record the changes made.
• Perform tests after major changes.

Common errors

Webhook not found

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

Invalid authToken

This may occur when the provided token does not meet the minimum security requirements.

Invalid URL

This may occur when the provided URL has an invalid format or is unavailable.

Invalid events

This may occur when invalid or unsupported events are sent.

Interrupted queue

If the interrupted attribute is set to true, events will stop being delivered until the queue is reactivated.

Operational impacts

Changes made through this endpoint directly affect the behavior of future events delivered by the webhook.

Incorrect changes to the URL, monitored events, or authToken may interrupt synchronization between systems.

For this reason, it is recommended to validate changes in a controlled environment before applying them to production.

Next steps

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

• Create webhook;
• List webhooks;
• Retrieve webhook;
• Remove webhook;
• Process events received by the integration.