Logs de Webhooks

Os Logs de Webhooks permitem acompanhar todas as tentativas de envio realizadas pelo Asaas, facilitando a identificação de falhas de comunicação, monitoramento da integração e análise do comportamento dos eventos enviados.

Essa funcionalidade é especialmente útil para investigar erros, validar se os eventos foram entregues corretamente e identificar situações que possam levar à penalização ou interrupção da fila.

❗️
Importante
O Asaas mantém os logs e eventos de Webhooks por até 14 dias.
Caso ocorram falhas de comunicação, um e-mail será enviado para o endereço configurado nas notificações do webhook.
Se a fila permanecer interrompida por mais de 14 dias, os eventos pendentes serão removidos permanentemente e não poderão ser recuperados.

Onde visualizar os Logs de Webhooks

É possível visualizar os Webhooks enviados e os erros ocorridos através da página de Logs de Webhooks, disponível na área de Integrações.

Também é possível consultar e configurar webhooks via API utilizando os endpoints da documentação. Entretanto, os logs de entrega estão disponíveis apenas pela interface web.

Logs de Webhooks para você verificar erros que aconteceram de comunicação.

O que pode ser analisado nos logs

Os logs permitem verificar:

Evento enviado;
Data e horário da tentativa;
Endpoint utilizado;
Código HTTP retornado pela aplicação;
Erros de comunicação;
Timeouts;
Quantidade de tentativas realizadas;
Situações que podem causar penalização ou interrupção da fila.

Essas informações ajudam a identificar rapidamente problemas na integração e a validar se o endpoint está respondendo corretamente.

Como utilizar os logs para investigar problemas

Em um fluxo comum de troubleshooting, recomendamos:

Receber alerta ou perceber ausência de eventos
↓
Acessar Logs de Webhooks
↓
Identificar o código HTTP retornado
↓
Verificar a causa do erro na aplicação
↓
Corrigir o problema
↓
Reativar a fila, se necessário
↓
Validar se os novos eventos estão sendo processados normalmente

Principais erros encontrados nos logs

Alguns erros comuns são:

400 Bad Request — o endpoint recebeu a requisição, mas retornou erro devido ao processamento ou validação.
403 Forbidden — normalmente causado por firewall, WAF ou regras de bloqueio.
404 Not Found — a URL configurada não existe ou não está acessível.
408 Read Timed Out — o endpoint demorou mais do que o tempo limite esperado.
500 Internal Server Error — falha interna da aplicação.
Connect Timed Out — falha de comunicação ou indisponibilidade do servidor.

Cada um desses cenários possui páginas específicas de troubleshooting na documentação.

Visualização de logs de Webhooks de subcontas

Os logs de Webhooks das subcontas também podem ser consultados pela conta principal.

No menu Integrações > Logs de Webhooks, utilize o filtro Tipo de Conta.

Ao selecionar Subcontas, será exibido um novo campo para busca pelo identificador da subconta.

O identificador é descritivo e a consulta é realizada para uma subconta por vez.

Boas práticas

📘
Recomendamos

Monitorar regularmente os logs de Webhooks.

Investigar códigos HTTP diferentes de 200.

Corrigir rapidamente falhas para evitar interrupção da fila.

Implementar processamento assíncrono para reduzir timeouts.

Utilizar idempotência para tratar possíveis reenvios.

Manter alertas e monitoramento sobre a disponibilidade do endpoint.

Reativar a fila assim que o problema for resolvido.

Evitar manter eventos pendentes por longos períodos.

Próximos passos

Após consultar os Logs de Webhooks, recomendamos conhecer: