Guia de Webhooks

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

Este endpoint permite listar todos os webhooks cadastrados na conta autenticada.

A consulta dos webhooks é útil para identificar configurações existentes, localizar o identificador de um webhook específico e validar informações antes de realizar operações como atualização ou remoção.

Quando utilizar

Este endpoint é recomendado quando:

• é necessário consultar os webhooks configurados na conta;
• deseja-se localizar o identificador (id) de um webhook;
• é necessário validar configurações existentes;
• será realizada a edição ou remoção de um webhook;
• deseja-se auditar os webhooks cadastrados na integração.

Dependências para utilização

Antes de utilizar este endpoint, é necessário:

• possuir uma conta Asaas ativa;
• possuir autenticação válida na API;
• possuir permissões para acesso aos webhooks da conta.

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

Parâmetros utilizados

📘

Importante

Recomenda-se utilizar paginação para consultas com grande quantidade de webhooks.

Comportamento da operação

Ao executar a consulta:

Consultar webhooks
↓
API localiza os registros da conta
↓
Lista de webhooks é retornada
↓
Integração utiliza os dados para consulta, edição ou remoção

A resposta retornará apenas os webhooks pertencentes à conta autenticada.

Os registros retornados possuem o identificador (id) necessário para operações posteriores.

Exemplo de requisição

GET /v3/webhooks?offset=0&limit=10

Exemplo:

GET /v3/webhooks?offset=0&limit=50

Exemplo de utilização

Um fluxo comum consiste em:

Consultar webhooks
↓
Localizar o ID do webhook
↓
Selecionar o webhook desejado
↓
Atualizar ou remover o recurso

Boas práticas

• Utilize paginação para grandes volumes de registros.
• Armazene internamente os identificadores dos webhooks mais importantes.
• Consulte os webhooks antes de realizar alterações na configuração.
• Evite criar múltiplos webhooks redundantes para os mesmos eventos.
• Mantenha as URLs configuradas revisadas periodicamente.

Erros comuns

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 não é válida.

Paginação incorreta

Pode ocorrer quando valores inconsistentes são utilizados em offset ou limit.

Limite excedido

O parâmetro limit aceita no máximo 100 registros por requisição.

Impactos operacionais

Em contas com muitos webhooks cadastrados, recomenda-se utilizar paginação para evitar consultas excessivas.

Além disso, a consulta periódica dos webhooks pode ser utilizada para auditoria e validação das configurações da integração.

Próximos passos

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

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