Ao ativar um Webhook, sempre que houver alterações nos recursos integrados dos eventos configurados, uma requisição POST será feita para o endereço configurado, contendo o evento e o recurso envolvido.

Habilitando um Webhook

Para ativar os Webhooks você deve acessar a área de Integrações do Asaas, na aba de Webhooks, e informe a URL da sua aplicação que deve receber o POST do Asaas. Você também pode configurar Webhooks via API. Confira os guias:

• Criar novo Webhook pela aplicação web
• Criar novo Webhook pela API

Boas práticas no uso de Webhooks

Utilize estas práticas para garantir que sua integração com Webhooks seja segura e funcione adequadamente.

Gerencie eventos duplicados

Os webhooks garantem a entrega "at least once" (ao menos uma entrega). Isso significa que seu endpoint pode receber ocasionalmente o mesmo evento de webhook mais de uma vez. Você pode ignorar eventos duplicados utilizando idempotência. Uma maneira é registrar os eventos que você processou e não registrar eles novamente, cada evento enviado pelos Webhooks possui um ID próprio.

Configure apenas os eventos necessários para sua aplicação

Configure apenas os eventos necessários para sua aplicação em cada Webhook. Receber eventos adicionais (ou todos os eventos) sobrecarrega seu servidor e não é recomendável.

Gerencie os eventos de forma assíncrona

Você pode encontrar problemas de escalabilidade se optar por eventos síncronos ou ter problemas de sobrecarregamento no host em caso de picos de eventos em endpoints, por isso é melhor configurar o processamento da fila de eventos de forma assíncrona.

Verifique se os eventos foram enviados pelo Asaas

Você tem a opção de utilizar um token para autenticar as requisições vindas do Asaas. Este token pode ser informado na configuração do Webhook. O token informado será enviado em todas as notificações no header asaas-access-token.

Retorne o mais rápido possível uma resposta 200

Para que o Asaas considere a notificação como processada com sucesso, o status HTTP da resposta deve ser 200. A sincronização é feita toda vez que há uma mudança em um evento, e caso seu sistema falhe em responder HTTP 200 15 vezes consecutivas, a fila de sincronização será interrompida. Novas notificações continuam sendo geradas e incluídas na fila de sincronia, porém não são enviadas para a sua aplicação. Após certificar-se que seu sistema responderá HTTP 200 para o Asaas basta reativar fila de sincronia acessando a área Minha Conta, aba Integração, todos os eventos pendentes serão processados em ordem cronológica.

Fique atento para eventuais falhas de comunicação

Se a sua aplicação retornar qualquer resposta HTTP que não é 200, a sua fila de eventos será interrompida e você receberá uma comunicação do Asaas para avisá-lo, fique atento para evitar ter problemas de sincronização de eventos.

❗️

Atenção

• O Asaas guarda eventos de Webhooks por 14 dias. Você receberá um e-mail caso haja algum problema de comunicação e seus Webhooks pararem de funcionar.
• Caso sua fila seja pausada, é de extrema importância que você resolva qualquer problema para evitar perder informações importantes.
• Os eventos que estiverem mais de 14 dias parados na fila serão excluídos permanentemente.