FAQ de Webhooks

Esta página reúne respostas rápidas sobre entrega, retentativas, idempotência, ordem dos eventos, segurança e troubleshooting de Webhooks.

Se esta for sua primeira integração, consulte primeiro a Introdução - Webhooks e o guia Receba eventos do Asaas no seu endpoint de Webhook.

Qual código HTTP meu endpoint deve retornar?

Retorne HTTP 200 para confirmar a entrega do evento.

Qualquer outro código, inclusive outros retornos da família 2xx, é tratado como falha e pode iniciar o processo de retentativas e penalização.

Consulte também Fila pausada e Penalização de filas.

O Asaas faz novas tentativas de envio?

Sim. Quando uma entrega falha, o Asaas realiza novas tentativas com intervalos progressivos.

Após 15 falhas consecutivas, a fila daquela configuração de Webhook é interrompida.

Enquanto a fila estiver interrompida, novos eventos continuam sendo gerados e armazenados, mas deixam de ser enviados até a reativação.

Consulte Penalização de filas para conhecer os intervalos entre as tentativas.

O mesmo evento pode ser enviado mais de uma vez?

Sim. Os Webhooks utilizam o modelo de entrega at least once, portanto o mesmo evento pode ser recebido mais de uma vez.

O id permanece igual nas reentregas do mesmo evento.

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

Use o id como chave de idempotência. Se evt_123456 já tiver sido persistido, não execute novamente a mesma regra de negócio.

Consulte Como implementar idempotência em Webhooks.

Os eventos chegam na ordem em que aconteceram?

Depende do tipo de envio configurado.

Sequencial

O envio Sequencial preserva a ordem dos eventos.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["PAYMENT_CREATED"] --> B["PAYMENT_CONFIRMED"]
    B --> C["PAYMENT_RECEIVED"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

    class A inicio
    class B validacao
    class C sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Não Sequencial

No envio Não Sequencial, eventos podem ser entregues simultaneamente e não há garantia de ordem entre notificações diferentes.

Consulte Tipos de envio para escolher o comportamento adequado à sua integração.

Devo concluir todo o processamento antes de responder?

Não. Persista o evento, confirme o recebimento com HTTP 200 e execute a regra de negócio em segundo plano.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receber o Webhook"] --> B["Persistir o evento"]
    B --> C["Retornar HTTP 200"]
    C --> D["Processar de forma assíncrona"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

    class A inicio
    class B,C validacao
    class D sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

Retorne HTTP 200 somente depois de confirmar que o evento foi persistido. Isso permite processar a regra de negócio posteriormente sem depender de uma nova entrega.

Qual é o tempo máximo de resposta?

O Asaas aguarda até 10 segundos pela resposta do endpoint.

Se esse tempo for excedido, a tentativa é considerada uma falha.

Consulte Erro 408 - Read Timed Out.

Por quanto tempo os eventos ficam armazenados?

Eventos pendentes permanecem armazenados por até 14 dias.

Se uma fila permanecer interrompida, os eventos mais antigos que ultrapassarem esse período serão removidos permanentemente.

Consulte Fila pausada.

Onde posso consultar falhas de entrega?

No menu Integrações, acesse Logs de Webhooks.

Os logs permitem verificar informações como:

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

Consulte Logs de Webhooks.

O Asaas envia Bearer Token nos Webhooks?

Não. Os Webhooks não utilizam autenticação padrão com Bearer Token ou Basic Auth.

Para validar as notificações, configure um authToken no Webhook. O valor é enviado em todas as notificações no header:

asaas-access-token

Não utilize uma API Key do Asaas como authToken.

Consulte Criar novo Webhook pela API para conhecer os requisitos do token.

O Asaas segue redirecionamentos HTTP?

Não.

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

• 301;
• 302;
• 307;
• 308.

Configure o Webhook com a URL final que responderá diretamente à requisição POST.

Consulte Outros erros.

Qual Content-Type é utilizado?

Os eventos são enviados como JSON:

Content-Type: application/json

Seu endpoint deve aceitar e interpretar esse formato.

Como interpretar os erros mais comuns?

Para outros códigos HTTP, consulte Outros erros.

Posso restringir o endpoint aos IPs do Asaas?

Sim. Se sua infraestrutura utiliza restrições por origem, configure uma allowlist com os IPs oficiais utilizados pelos Webhooks em Produção.

Consulte IPs oficiais do Asaas.

Se utilizar Cloudflare, consulte também Bloqueio do Firewall na CloudFlare.

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

Sim. Em Sandbox podem existir IPs adicionais utilizados no envio dos Webhooks.

Se utilizar regras de Firewall ou WAF, valide os dois ambientes separadamente. Não considere a lista de IPs de Produção como garantia de cobertura do Sandbox.

Consulte IPs oficiais do Asaas.

Como validar se a integração está funcionando corretamente?

Verifique se:

• as entregas retornam HTTP 200;
• a fila do Webhook está ativa;
• não existem falhas recorrentes nos Logs de Webhooks;
• reentregas do mesmo id não executam a regra de negócio novamente;
• o recebimento está desacoplado de processamentos demorados;
• o endpoint e suas dependências estão monitorados.

Próximos passos

• Entenda como funcionam os Webhooks
• Crie um Webhook pela aplicação web
• Crie um Webhook pela API
• Implemente o recebimento dos eventos
• Implemente idempotência
• Monitore os Logs de Webhooks