Logs de Webhooks

Use os Logs de Webhooks para verificar as tentativas de entrega realizadas pelo Asaas, identificar falhas no endpoint e acompanhar situações que podem 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.

Acesse os Logs de Webhooks

Acesse Logs de Webhooks na área de Integrações da sua conta.

Os logs de entrega estão disponíveis somente pela interface web. A configuração dos Webhooks também pode ser gerenciada pela API.

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

O que verificar nos logs

Para cada tentativa de envio, utilize os logs para analisar:

Informação	Como utilizar
Evento enviado	Identifique qual notificação apresentou problema.
Data e horário	Relacione a tentativa aos logs da sua aplicação.
Endpoint	Confirme qual URL recebeu a requisição.
Código HTTP	Identifique como sua aplicação respondeu ao Asaas.
Erro de comunicação	Verifique falhas ocorridas antes ou durante a conexão.
Timeout	Identifique demora na conexão ou na resposta do endpoint.
Quantidade de tentativas	Acompanhe a evolução das retentativas e da penalização.

Como investigar uma falha

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Perceber ausência de eventos<br/>ou receber um alerta"] --> B["Acessar Logs de Webhooks"]
    B --> C["Identificar o erro<br/>ou código HTTP"]
    C --> D["Verificar a causa<br/>na aplicação"]
    D --> E["Corrigir o endpoint"]
    E --> F{"A fila foi interrompida?"}

    F --> FSim(("Sim"))
    F --> FNao(("Não"))

    FSim --> G["Reativar a fila"]
    FNao --> H["Validar novos eventos"]
    G --> H

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class B,C,D,E,G validacao
    class F decisao
    class H sucesso

    class FSim respostaSim
    class FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#22C55E,stroke-width:4px
    linkStyle 6 stroke:#EF4444,stroke-width:4px

Se a fila estiver interrompida, corrija a causa da falha antes de reativá-la.

Consulte como reativar uma fila interrompida.

Principais erros encontrados nos logs

Use o código ou erro registrado para direcionar a investigação.

Erro	O que indica	Como investigar
`400 Bad Request`	A requisição chegou ao endpoint, mas foi rejeitada pela aplicação.	Erro 400 (Bad Request)
`403 Forbidden`	A requisição chegou ao servidor, mas alguma regra de segurança bloqueou o acesso.	Erro 403 (Forbidden)
`404 Not Found`	A URL ou rota configurada não foi encontrada.	Erro 404 (Not Found)
`408 Read Timed Out`	A conexão foi estabelecida, mas o endpoint não respondeu dentro do tempo esperado.	Erro 408 - Read Timed Out
`500 Internal Server Error`	A aplicação apresentou uma falha interna durante o processamento.	Erro 500 (Internal Server Error)
`Connect Timed Out`	O Asaas não conseguiu estabelecer conexão com o servidor.	Erro Connect Timed Out

Falhas consecutivas entram no mecanismo de penalização da fila. Após 15 falhas consecutivas, a fila daquele Webhook pode ser interrompida.

Entenda a penalização de filas.

Consulte logs de subcontas

A conta principal também pode consultar os Logs de Webhooks das subcontas.

Em Integrações > Logs de Webhooks:

selecione o filtro Tipo de Conta;
escolha Subcontas;
informe o identificador da subconta que deseja consultar.

A consulta é realizada para uma subconta por vez.

📘
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

Updated 5 days ago

Did this page help you?