Guia de Webhooks

Confira o guia de Webhooks para mais informações.

Este endpoint permite atualizar as configurações de um webhook já cadastrado.

A operação pode ser utilizada para alterar informações como URL de destino, eventos monitorados, token de autenticação, tipo de envio e status do webhook.

Quando utilizar

Este endpoint é recomendado quando:

• é necessário alterar a URL de destino do webhook;
• novos eventos precisam ser adicionados ou removidos;
• deseja-se ativar ou desativar o webhook;
• é necessário interromper ou reativar a fila de sincronização;
• o authToken precisa ser substituído;
• ajustes operacionais precisam ser realizados em uma integração existente.

Dependências para utilização

Antes de atualizar um webhook, é necessário:

• possuir uma conta Asaas ativa;
• possuir autenticação válida na API;
• possuir o identificador (id) do webhook;
• garantir que o webhook pertença à conta autenticada.

Sem essas condições, a atualização não poderá ser realizada.

Parâmetros utilizados

📘

Importante

Caso seja necessário atualizar o authToken, recomenda-se seguir os requisitos de segurança descritos na documentação de criação de webhooks.

O authToken deve possuir entre 32 e 255 caracteres.

Comportamento da operação

Ao atualizar um webhook:

Webhook existente
↓
Atualização das configurações
↓
Novas informações são persistidas
↓
Próximos eventos utilizarão a nova configuração

As alterações passam a ser consideradas para os próximos eventos enviados.

Eventos já processados não são afetados pela atualização.

Exemplo de requisição

PUT /v3/webhooks/wh_123456789

{
  "name": "Webhook de pagamentos",
  "url": "https://www.suaaplicacao.com.br/webhooks/asaas",
  "enabled": true,
  "interrupted": false,
  "sendType": "SEQUENTIALLY",
  "authToken": "token-seguro-com-mais-de-32-caracteres",
  "events": [
    "PAYMENT_RECEIVED",
    "PAYMENT_OVERDUE"
  ]
}

Exemplo de utilização

Um fluxo comum consiste em:

Consultar webhook
↓
Identificar necessidade de alteração
↓
Atualizar configurações
↓
Salvar alterações
↓
Continuar recebendo eventos normalmente

Boas práticas

• Consulte o webhook antes de realizar alterações.
• Utilize um authToken forte.
• Atualize apenas os eventos necessários.
• Mantenha a URL de destino disponível para recebimento das notificações.
• Registre internamente as alterações realizadas.
• Realize testes após mudanças importantes.

Erros comuns

Webhook não encontrado

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

AuthToken inválido

Pode ocorrer quando o token informado não atende aos requisitos mínimos de segurança.

URL inválida

Pode ocorrer quando a URL informada possui formato incorreto ou está indisponível.

Eventos incorretos

Pode ocorrer quando são enviados eventos inválidos ou incompatíveis.

Fila interrompida

Caso o atributo interrupted seja definido como true, os eventos deixarão de ser enviados até que a fila seja reativada.

Impactos operacionais

Alterações realizadas neste endpoint impactam diretamente o comportamento dos próximos eventos enviados pelo webhook.

Mudanças incorretas na URL, nos eventos monitorados ou no authToken podem interromper a sincronização entre os sistemas.

Por esse motivo, recomenda-se validar as alterações em ambiente controlado antes de aplicá-las em produção.

Próximos passos

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

• Criar webhook;
• Listar webhooks;
• Consultar webhook;
• Remover webhook;
• Processar os eventos recebidos pela integração.