This endpoint removes a webhook configured in the account.

The request uses the webhook identifier (id) in the endpoint:

DELETE /v3/webhooks/{id}

When a webhook is removed:

• new events are no longer sent to the configured URL;
• Asaas immediately stops delivery attempts related to that webhook;
• the integration no longer receives automatic notifications associated with the removed configuration.

When to use this endpoint

This endpoint should be used when it is necessary to discontinue receiving automatic notifications, for example:

• decommissioning an integration;
• changing the URL used to receive events;
• removing old environments or invalid URLs;
• shutting down an integrated application;
• restructuring the webhook architecture.

❗️

Attention

This action cannot be undone.

After removing the webhook, a new configuration must be created if you want to receive events automatically again.

Dependencies for use

Before removing a webhook, it is necessary that:

• there is an active Asaas account;
• the request is performed using a valid API Key;
• the webhook belongs to the authenticated account;
• the webhook identifier (id) is available;
• the integration does not rely exclusively on the webhook being removed.

Without these conditions, the operation cannot be completed successfully.

Important rules

Removing a webhook is a permanent operation.

To perform the operation:

• the request must be authenticated using a valid API Key;
• only webhooks belonging to the authenticated account can be removed;
• the identifier (id) must correspond to an existing webhook;
• after deletion, new events are no longer sent automatically;
• to receive events again, a new webhook must be created.

The operation does not remove events already processed or historical records stored in the application.

Impact of removal

After deletion:

• future events will no longer be sent to the removed webhook;
• automatic retry attempts will stop occurring;
• the removed identifier cannot be reused.

If your application still depends on receiving events, it is recommended to verify that another active webhook is properly configured.

Operation behavior

Deletion occurs immediately.

If the provided identifier does not exist, a resource not found error will be returned.

Repeated requests for a webhook that has already been removed will return an error, since the resource no longer exists.

The operation is synchronous and does not provide a restore mechanism.

If there are integrations that depend on the removed webhook, they will stop receiving future notifications.

Parameters used

Headers used

Response codes

Request example

DELETE /v3/webhooks/wh_123456789
Host: api.asaas.com
access_token: $YOUR_API_KEY
Content-Type: application/json

Response example

{
  "deleted": true
}

Common errors

Webhook not found

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

Invalid API Key

Occurs when the request is sent without valid authentication.

Integration stops receiving events

After deletion, new events are no longer sent to the previously configured URL.

📘

Recommended

Before removing a webhook, verify that another webhook is active or that the integration no longer depends on notifications.

Related content

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

• Create new webhook;
• List webhooks;
• Retrieve a webhook;
• Update existing webhook;
• Webhooks Guide;
• API Authentication.