Webhooks

Os webhooks, também chamados 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, os webhooks ocorrem 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 acessar o Menu do usuário, 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 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;

• E-mail: 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 a erros no tratamento da sua aplicação, a fila de sincronização será automaticamente interrompida. Se isso acontecer, 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 no prazo máximo de 14 dias. Após esse período, os eventos serão excluídos permanentemente.

Todas as instruções para configuração dos webhooks, além do detalhamento dos eventos, modelo de configuração, exemplo dos POSTs enviados, e possíveis erros no webhook você pode localizar em nossa documentação, clicando aqui. Já para visualizar os fluxos possíveis para o webhook de acordo com cada forma de pagamento e situação, clique aqui.