O Webhook, também chamado de callback ou postback, é uma funcionalidade que permite que sua aplicação receba informações do ASAAS em tempo real.  Assim como ao utilizar a nossa API a sua aplicação se comunica com o Asaas, o Webhook ocorre no sentido contrário: o Asaas notifica a sua aplicação sobre os eventos que ocorrem na sua conta.

Dessa maneira, você consegue fazer a conciliação entre a situação de suas cobranças e notas fiscais dentro do ASAAS, diretamente na sua aplicação, desconsiderando a necessidade de execução de requisições para obter o status de cada uma de suas cobranças ou notas fiscais.

A funcionalidade consiste em configurar uma URL da sua aplicação que será a responsável por receber do ASAAS, todos os eventos de sincronização. Os mesmos são enviados no formato JSON, através de requisições POST.

Para realizar a configuração dentro do Asaas do seu Webhook, você deve navegar pelo menu Minha Conta > Integração > Webhook para Cobranças (ou Notas Fiscais).

Na parte superior, você encontrará um link que lhe direcionará para a nossa documentação, e logo abaixo um outro link para que você possa acessar os LOGs de seus webhooks.

Dentro dos LOGs é possível realizar filtros para buscar uma determinada data, ou uma determinada cobrança, e você também poderá visualizar os eventos enviados e as respostas da sua aplicação para analisar e debugar qualquer possível erro nas sincronizações.

Na parte das configurações, você encontrará as seguintes opções:

Ativar Webhook: Opção para manter ativo ou desativar as sincronizações do Webhook. Caso a opção esteja "Não", nenhum evento será criado ou inserido em fila.

URL: Aqui é o campo para informar a URL da sua aplicação que será responsável pelo recebimento e tratamentos dos eventos disparados pelo Asaas. É necessário um desenvolvimento prévio desse tratamento para interpretação dos POST Json disparados por nós.

Email: Caso ocorra alguma interrupção ou falha na sincronização dos webhooks, um e-mail de alerta será disparado para o destinatário configurado nesse campo.

Versão da API: Variando entre v2 e v3, ainda disponível por questões de retrocompatibilidade. A versão atual da API do Asaas é a v3, portanto, novas integrações baseadas nesse recurso devem utilizar a v3 como opção para esse campo.

Token de Autenticação: Para acrescentar uma camada extra de segurança, você pode adicionar um token de autenticação que será disparado no header de todas as requisições enviadas do Asaas para a sua aplicação. Esse token será enviado no header asaas_access_token. Assim, você pode prevenir e tratar somente POSTs recebidos que contenham esse header especificamente, evitando algum disparo indevido contra seus endpoints.

Status fila de Sincronização: Caso ocorra alguma interrupção na fila devido à erros no tratamento da sua aplicação, a fila de sincronização automaticamente será interrompida. Caso isso aconteça, você poderá analisar os LOGs dos webhooks para entender o motivo da interrupção, e após o tratamento da falha, reativar novamente sua fila marcando a opção "Ativa" e salvando a configuração. Enquanto o status da fila estiver "Interrompida", os eventos continuarão sendo gerados normalmente e permanecerão em fila até que a mesma seja reativada novamente.

-

Todas as instruções para configuração dos Webhooks, além do detalhamento dos eventos, modelo de configuração, exemplo dos POST enviados e possíveis erros no webhook você pode localizar em nossa documentação, clicando aqui.

Para visualizar os fluxos possíveis para o Webhook de acordo com cada forma de pagamento e situação, clique aqui.

Avalie este artigo nos emojis abaixo. Ajude a entender como estamos nos saindo!