Introdução

Um webhook é uma forma automatizada de enviar informações entre sistemas quando certos eventos ocorrem. Quando você ativa um webhook, ele passará a enviar requisições POST para o endereço configurado sempre que determinado evento acontecer. Essa requisição incluirá informações sobre o evento e o recurso envolvido.

Habilitando um webhook

Para ativar os webhooks você pode acessar a área de Integrações do Base ERP: Menu do usuário > Configurações > Integrações > Webhooks. Lá, você deverá informar a URL da sua aplicação que deve receber o POST do Base. Além disso, você também pode configurar webhooks via API. Confira os guias:

É possível cadastrar até 10 URLs de webhooks diferentes, e em cada uma você define quais eventos quer receber.

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 de fazer isso é registrando os eventos que já foram processados e ignorá-los caso sejam enviados novamente. Cada evento enviado pelos webhooks possui um ID próprio, que se repete caso se trate do mesmo evento.

Você confere mais informações sobre idempotência no Guia do Asaas.

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

Configure apenas os tipos de eventos necessários para sua aplicação em cada webhook. Receber tipos de eventos adicionais (ou todos os tipos de 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 implementar o processamento da fila de eventos de forma assíncrona.

Verifique se os eventos foram enviados a partir do Base

Para impedir que a sua aplicação receba requisições de outras origens, você tem a opção de utilizar um token para autenticar as requisições vindas do Base. 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 de sucesso

Para que o Base considere a notificação como processada com sucesso, o status HTTP da resposta deve ser maior ou igual a 200 e menor que 300. A sincronização é feita toda vez que há uma mudança em um evento, e caso seu sistema falhe em responder sucesso 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á uma resposta de sucesso para o Base, basta reativar fila de sincronia acessando a área de Integrações. 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 é da família 200, a sua fila de eventos será interrompida e você receberá um e-mail de comunicação do Asaas para deixá-lo ciente disso. Fique atento para evitar ter problemas de sincronização de eventos.

❗️
Atenção

O Base 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 em até 14 dias para evitar perder informações importantes.

Os eventos que estiverem mais de 14 dias parados na fila serão excluídos permanentemente.