Este endpoint permite remover a penalização (backoff) aplicada a uma configuração de webhook.

Quando um webhook apresenta falhas sucessivas na entrega dos eventos, mecanismos de proteção podem reduzir temporariamente a frequência das tentativas de envio. A operação de remoção da penalização permite restabelecer o fluxo normal de notificações.

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

POST /v3/webhooks/{id}/removeBackoff

Quando utilizar este endpoint

Esse endpoint deve ser utilizado quando:

• a fila de sincronização do webhook foi penalizada devido a falhas recorrentes;
• a aplicação responsável pelo recebimento dos eventos voltou a operar normalmente;
• a indisponibilidade da URL já foi corrigida;
• deseja-se restabelecer o envio dos eventos sem necessidade de recriar o webhook;
• problemas temporários de infraestrutura foram solucionados.

📘

Importante

Recomenda-se remover a penalização somente após corrigir a causa que provocou as falhas de sincronização.

Dependências para utilização

Antes de remover a penalização, é necessário que:

• exista uma conta Asaas ativa;
• a requisição seja autenticada utilizando uma API Key válida;
• a configuração do webhook pertença à conta autenticada;
• o identificador (id) da configuração esteja disponível;
• a aplicação receptora esteja novamente apta a processar os eventos recebidos.

Sem essas condições, a operação poderá falhar.

Regras importantes

A operação remove a penalização aplicada à configuração do webhook.

Para executar a operação:

• a configuração deve existir;
• a requisição deve ser autenticada;
• o identificador informado deve corresponder a um webhook da conta autenticada;
• recomenda-se validar previamente a disponibilidade da URL configurada.

Caso a origem das falhas não tenha sido corrigida, novas penalizações poderão ocorrer.

Comportamento da operação

Após a remoção da penalização:

Webhook penalizado
↓
Aplicação corrigida
↓
Remoção da penalização
↓
Retorno ao fluxo normal de entrega
↓
Novos eventos voltam a ser enviados

A operação não recria eventos já perdidos nem altera configurações do webhook.

Ela apenas remove a penalização aplicada ao mecanismo de entrega.

Impactos operacionais

A remoção da penalização permite que os eventos voltem a ser enviados normalmente.

Caso a aplicação continue indisponível:

• novas falhas poderão ocorrer;
• a fila poderá voltar a ser penalizada;
• a sincronização entre os sistemas poderá continuar comprometida.

Por esse motivo, recomenda-se validar completamente a infraestrutura antes de executar a operação.

Parâmetros utilizados

Cabeçalhos utilizados

Códigos de resposta

Exemplo de requisição

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

Exemplo de resposta

HTTP/1.1 204 No Content

Erros comuns

Configuração de webhook não encontrada

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.

Penalização volta a ocorrer

Pode acontecer quando a aplicação responsável pelo recebimento dos eventos continua apresentando indisponibilidade.

📘

Recomendado

Antes de remover a penalização, valide a disponibilidade da aplicação e monitore os logs de processamento dos eventos.

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;
• Remover um webhook;
• Guia de Webhooks;
• Autenticação da API.