Este endpoint remove um webhook configurado na conta.

A requisição utiliza o identificador do webhook (id) no endpoint:

DELETE /v3/webhooks/{id}

Quando um webhook é removido:

• novos eventos deixam de ser enviados para a URL configurada;
• o Asaas interrompe imediatamente as tentativas de entrega relacionadas àquele webhook;
• a integração deixa de receber notificações automáticas vinculadas à configuração removida.

Quando utilizar este endpoint

Esse endpoint deve ser utilizado quando for necessário descontinuar o recebimento de notificações automáticas, por exemplo:

• desativação de uma integração;
• troca da URL de recebimento de eventos;
• remoção de ambientes antigos ou URLs inválidas;
• encerramento de uma aplicação integrada;
• reestruturação da arquitetura de webhooks.

❗️

Atenção

Esta ação não pode ser desfeita.

Após a remoção do webhook, será necessário criar uma nova configuração caso deseje voltar a receber eventos automaticamente.

Dependências para utilização

Antes de remover um webhook, é necessário que:

• exista uma conta Asaas ativa;
• a requisição seja realizada com uma API Key válida;
• o webhook pertença à conta autenticada;
• o identificador (id) do webhook esteja disponível;
• a integração não dependa exclusivamente do webhook que será removido.

Sem essas condições, a operação não poderá ser concluída com sucesso.

Regras importantes

A remoção de um webhook é uma operação permanente.

Para executar a operação:

• a requisição deve ser autenticada utilizando uma API Key válida;
• somente webhooks pertencentes à conta autenticada podem ser removidos;
• o identificador (id) deve corresponder a um webhook existente;
• após a exclusão, novos eventos deixam de ser enviados automaticamente;
• para voltar a receber eventos será necessário criar um novo webhook.

A operação não remove eventos já processados ou registros históricos existentes na aplicação.

Impacto da remoção

Após a exclusão:

• eventos futuros não serão mais enviados para o webhook removido;
• tentativas automáticas de retry deixam de ocorrer;
• o identificador removido não poderá ser reutilizado.

Caso sua aplicação ainda dependa do recebimento de eventos, recomenda-se validar previamente se existe outro webhook ativo configurado corretamente.

Comportamentos da operação

A exclusão ocorre de forma imediata.

Caso o identificador informado não exista, será retornado erro de recurso não encontrado.

Chamadas repetidas para um webhook já removido retornarão erro, uma vez que o recurso deixa de existir.

A operação é síncrona e não possui mecanismo de restauração.

Caso existam integrações dependentes do webhook removido, elas deixarão de receber notificações futuras.

Parâmetros utilizados

Cabeçalhos utilizados

Códigos de resposta

Exemplo de requisição

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

Exemplo de resposta

{
  "deleted": true
}

Erros comuns

Webhook não encontrado

Ocorre quando o identificador informado não existe ou não pertence à conta autenticada.

API Key inválida

Ocorre quando a requisição é enviada sem autenticação válida.

Integração deixa de receber eventos

Após a exclusão, novos eventos deixam de ser enviados para a URL anteriormente configurada.

📘

Recomendado

Antes de remover um webhook, valide se existe outro webhook ativo ou se a integração não depende mais das notificações.

Conteúdos relacionados

Dependendo da necessidade da integração, os conteúdos abaixo podem complementar a implementação:

• Criar novo webhook;
• Listar webhooks;
• Recuperar um único webhook;
• Atualizar webhook existente;
• Guia de Webhooks;
• Autenticação da API.