FAQ de Webhooks

Esta FAQ reúne as dúvidas mais comuns sobre Webhooks do Asaas e complementa os demais conteúdos da documentação.

Ela é recomendada tanto para quem está iniciando uma integração quanto para quem deseja entender comportamentos específicos relacionados a entrega de eventos, filas, idempotência e tratamento de falhas.

Caso seja sua primeira integração, recomendamos iniciar pelos conteúdos de Introdução, Criação de Webhooks e Recebimento de eventos antes de consultar esta página.

Meu webhook precisa responder qual código HTTP?

Para que o evento seja considerado entregue com sucesso, sua aplicação deve retornar HTTP 200.

Qualquer outro código (3xx, 4xx, 5xx, etc.) será tratado como falha e iniciará o processo de penalização da fila.

📘
Importante
Embora existam diversos códigos de sucesso da família 2xx, atualmente o Asaas considera apenas o retorno HTTP 200 como sucesso no processamento do evento.

Veja também:

O Asaas faz novas tentativas de envio?

Sim.

Quando ocorre uma falha, o Asaas realiza novas tentativas automaticamente.

Os intervalos entre as tentativas aumentam progressivamente até que, após 15 falhas consecutivas, a fila seja interrompida.

Mesmo com a fila interrompida, os eventos continuam armazenados por até 14 dias.

Veja também:

O webhook pode ser enviado mais de uma vez?

Sim.

Por questões de disponibilidade e retentativas, um mesmo evento pode ser entregue mais de uma vez.

Por esse motivo, recomenda-se implementar idempotência utilizando o campo id do evento.

Exemplo:

{
  "id": "evt_123456",
  "event": "PAYMENT_RECEIVED"
}

Se o evento evt_123456 já tiver sido processado anteriormente, ele deve ser ignorado.

Veja também:

Como implementar idempotência em Webhooks

Os eventos chegam na ordem em que aconteceram?

Depende do tipo de envio configurado.

Sequencial

Os eventos são enviados respeitando a ordem em que ocorreram.

Exemplo:

PAYMENT_CREATED
↓
PAYMENT_CONFIRMED
↓
PAYMENT_RECEIVED

Não sequencial

Os eventos são enviados em paralelo, priorizando desempenho e vazão.

Nesse modo, não existe garantia de ordem entre eventos diferentes.

Veja também:

Tipos de envio

Posso processar o webhook e responder depois?

Sim.

A prática recomendada é responder HTTP 200 o mais rápido possível e realizar o processamento em segundo plano.

Exemplo:

Receber webhook
↓
Salvar evento em fila
↓
Retornar HTTP 200
↓
Processar evento de forma assíncrona

Isso reduz o risco de timeout.

Veja também:

Erro 408 - Read Timed Out

Qual é o tempo máximo de resposta esperado?

O Asaas aguarda até 10 segundos pela resposta do seu servidor.

Caso esse prazo seja excedido, a tentativa é considerada falha.

Veja também:

Erro 408 - Read Timed Out

Quanto tempo os eventos ficam armazenados?

Os eventos permanecem disponíveis por até 14 dias.

Caso a fila esteja interrompida e não seja reativada dentro desse período, os eventos mais antigos serão removidos permanentemente.

⚠️
Importante
Eventos excluídos após o período de retenção não podem ser recuperados.

Veja também:

Onde posso consultar os erros dos webhooks?

Acesse:

Integrações → Logs de Webhooks

Nos logs é possível visualizar:

código HTTP retornado;
data e horário da tentativa;
payload enviado;
mensagem de erro;
status da entrega.

Veja também:

Logs de Webhooks

O Asaas envia Bearer Token nos webhooks?

Não.

Os Webhooks do Asaas não utilizam autenticação padrão Bearer Token.

Caso sua aplicação exija autenticação, recomenda-se implementar uma validação própria.

O Asaas segue redirecionamentos HTTP?

Não.

Os seguintes retornos não são seguidos automaticamente:

A URL configurada deve responder diretamente ao POST enviado pelo webhook.

Veja também:

Outros erros

Qual Content-Type é utilizado?

Os eventos são enviados utilizando:

Content-Type: application/json

Seu endpoint deve estar preparado para receber payloads JSON.

Como evitar eventos duplicados?

Recomendamos:

utilizar o campo id como chave de idempotência;
armazenar eventos já processados;
ignorar reentregas.

Veja também:

Como implementar idempotência em Webhooks

O que acontece se meu servidor retornar erro?

O evento será reenviado.

Falhas consecutivas geram penalização progressiva e, após 15 tentativas sem sucesso, a fila é interrompida.

Veja também:

O que significa erro 403?

Significa que a requisição foi bloqueada antes do processamento.

As causas mais comuns são:

CloudFlare;
WAF;
Firewall;
restrição por IP;
validações internas.

Veja também:

O que significa erro 404?

Significa que a URL configurada não foi encontrada.

As causas mais comuns são:

URL incorreta;
endpoint removido;
rota alterada.

Veja também:

Erro 404 (Not Found)

O que significa erro 408?

Significa que a aplicação demorou mais de 10 segundos para responder.

Veja também:

Erro 408 - Read Timed Out

O que significa erro 500?

Significa que ocorreu uma exceção interna no servidor da aplicação.

Veja também:

Erro 500 (Internal Server Error)

Posso utilizar firewall para aceitar somente requisições do Asaas?

Sim.

É possível utilizar os IPs oficiais do Asaas para criar regras de allowlist.

Veja também:

Existe diferença entre Sandbox e Produção?

Sim.

Em ambiente Sandbox podem existir IPs adicionais utilizados nos envios.

Por esse motivo, caso utilize firewall ou CloudFlare, é importante validar ambos os ambientes.

Veja também:

IPs oficiais do Asaas

Como sei se minha integração está saudável?

Uma integração saudável apresenta:

respostas HTTP 200;
fila ativa;
baixo volume de erros nos logs;
processamento idempotente;
tratamento assíncrono;
monitoramento do endpoint;
baixa quantidade de eventos penalizados.

Ordem recomendada de leitura

Se você estiver iniciando uma integração com Webhooks, recomendamos a seguinte sequência: