Guia de Webhooks

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

Este endpoint permite criar um novo webhook para receber notificações automáticas sobre eventos ocorridos na conta Asaas.

Os webhooks são utilizados para manter sistemas sincronizados sem necessidade de consultas frequentes à API. Sempre que um evento configurado ocorrer, uma notificação será enviada para a URL cadastrada.

Quando utilizar

Este endpoint é indicado para integrações que precisam reagir automaticamente a eventos da plataforma, como:

• confirmação de pagamentos;
• vencimento de cobranças;
• cancelamentos;
• estornos;
• alterações em assinaturas;
• eventos relacionados a Pix, transferências e outros recursos da API.

Em vez de consultar constantemente os recursos da API, recomenda-se utilizar webhooks para receber atualizações em tempo real.

Dependências para utilização

Antes de criar um webhook, é necessário:

• possuir uma conta Asaas ativa;
• possuir autenticação válida na API;
• disponibilizar uma URL acessível pela internet;
• definir quais eventos deverão ser monitorados;
• possuir uma aplicação capaz de processar as notificações recebidas.

Sem essas condições, o webhook não poderá ser criado corretamente.

Eventos de Webhooks

Na configuração do webhook é necessário informar quais eventos deverão gerar notificações.

📘

Eventos disponíveis

Consulte a lista completa de eventos suportados para definir quais notificações serão recebidas.

Parâmetros utilizados

📘

Importante

O parâmetro authToken deve possuir entre 32 e 255 caracteres e deve ser armazenado de forma segura.

Comportamento da operação

Após a criação do webhook, o fluxo segue o comportamento abaixo:

Webhook criado
↓
Evento ocorre na conta Asaas
↓
Asaas envia a notificação
↓
Aplicação processa o evento
↓
Integração atualiza seus dados

Os webhooks possuem um identificador único (id) retornado na criação.

Esse identificador pode ser utilizado posteriormente para:

• consultar as configurações do webhook;
• editar um webhook existente;
• remover um webhook;
• listar webhooks configurados na conta.

As notificações são enviadas para a URL cadastrada e o sistema destinatário deve estar preparado para processar os eventos recebidos.

🚧

Atenção

Recomenda-se que o processamento dos eventos seja idempotente, evitando ações duplicadas caso o mesmo evento seja recebido mais de uma vez.

Exemplo de requisição

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

Neste exemplo, o webhook será criado ativo e enviará notificações para a URL configurada sempre que uma cobrança for recebida ou vencida.

Cuidados importantes

🚧

Atenção

Recomenda-se utilizar um authToken forte para validar a origem das notificações.

Além disso:

• a URL configurada deve estar disponível para receber requisições;
• o processamento dos eventos deve ser idempotente, evitando duplicidades;
• o sistema deve responder adequadamente às notificações recebidas;
• recomenda-se monitorar falhas de sincronização e indisponibilidades.

Exemplo de utilização

Um fluxo comum consiste em:

Criar webhook
↓
Selecionar PAYMENT_RECEIVED
↓
Cliente realiza pagamento
↓
Asaas envia a notificação
↓
Sistema atualiza o pedido automaticamente

Boas práticas

• Configure apenas os eventos necessários para sua integração.
• Utilize uma URL dedicada para recebimento dos eventos do Asaas.
• Valide o authToken recebido antes de processar a notificação.
• Registre logs dos eventos recebidos para auditoria e troubleshooting.
• Implemente processamento idempotente para evitar duplicidade de ações.
• Monitore falhas de entrega e interrupções na fila do webhook.

📘

Importante

Após a criação do webhook, recomenda-se realizar testes para garantir que os eventos estejam sendo recebidos e processados corretamente.

Erros comuns

URL inválida ou inacessível

Ocorre quando a URL informada não está disponível publicamente ou não aceita requisições externas.

AuthToken inválido

Pode ocorrer quando o token informado não atende aos requisitos mínimos ou não é validado corretamente pela aplicação receptora.

Eventos não configurados

Pode ocorrer quando nenhum evento relevante foi selecionado para envio das notificações.

Fila interrompida

Quando a fila de sincronização está interrompida, os eventos deixam de ser enviados normalmente.

Processamento duplicado

Pode ocorrer quando a aplicação receptora não implementa tratamento idempotente dos eventos.

Impactos operacionais

A indisponibilidade da URL configurada ou falhas no processamento podem ocasionar atrasos na sincronização entre os sistemas.

Por esse motivo, recomenda-se:

• monitorar os recebimentos dos webhooks;
• manter alta disponibilidade da aplicação receptora;
• registrar logs das notificações recebidas;
• validar a autenticidade das mensagens utilizando o authToken;
• acompanhar eventuais interrupções da fila de sincronização.

Próximos passos

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

• Consultar webhook;
• Atualizar webhook;
• Remover webhook;
• Processar os eventos recebidos pela integração.

🚧

Atenção

Os Webhooks possuem um identificador (id). Utilize esse identificador para consultar, editar ou remover o recurso posteriormente.