Guia de Webhooks

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

Este endpoint permite recuperar as configurações de um webhook específico através do seu identificador único (id).

A consulta é útil para validar informações do webhook, identificar eventos monitorados, verificar se ele está ativo e obter dados necessários para operações posteriores.

Quando utilizar

Este endpoint é recomendado quando:

• é necessário consultar um webhook específico;
• deseja-se validar suas configurações atuais;
• será realizada a atualização ou remoção do webhook;
• é necessário verificar se o webhook está ativo;
• deseja-se auditar as configurações de uma integração existente.

Dependências para utilização

Antes de realizar a consulta, é 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 consulta não poderá ser realizada.

Parâmetros utilizados

📘

Importante

O parâmetro id corresponde ao identificador do webhook e não à URL configurada ou aos eventos monitorados.

Comportamento da operação

Ao executar a consulta:

Webhook existente
↓
Consulta pelo ID
↓
API localiza o recurso
↓
Dados do webhook são retornados
↓
Integração utiliza as informações

A resposta contém as configurações atuais do webhook, incluindo eventos monitorados e informações necessárias para gerenciamento do recurso.

Exemplo de requisição

GET /v3/webhooks/wh_123456789

Exemplo:

GET /v3/webhooks/wh_000001

Exemplo de utilização

Uma integração típica segue o fluxo abaixo:

Listar webhooks
↓
Localizar o ID desejado
↓
Consultar webhook específico
↓
Validar configurações
↓
Atualizar ou remover o recurso

Boas práticas

• Armazene o identificador do webhook após sua criação.
• Consulte o recurso antes de realizar alterações.
• Utilize logs para auditoria das configurações.
• Evite manter múltiplos webhooks redundantes para os mesmos eventos.
• Revise periodicamente as URLs e eventos configurados.

Erros comuns

Webhook não encontrado

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

Requisição GET com body preenchido

Chamadas GET devem possuir body vazio.

Quando um body é enviado, a API poderá retornar erro 403.

Token inválido

Pode ocorrer quando a autenticação da API é inválida ou expirou.

Identificador incorreto

Pode ocorrer quando é utilizado um ID inexistente ou pertencente a outro recurso.

Impactos operacionais

A consulta do webhook permite validar configurações e reduzir riscos de alterações incorretas.

Recomenda-se sempre consultar o recurso antes de atualizá-lo ou removê-lo, garantindo que a operação seja realizada sobre o webhook correto.

Próximos passos

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

• Criar webhook;
• Listar webhooks;
• Atualizar webhook;
• Remover webhook;
• Processar eventos recebidos pelos webhooks.