Webhooks

Integre com Webhooks

Receba notificações automáticas quando ocorrerem eventos na conta Asaas.

O Asaas envia requisições POST para a URL configurada, permitindo que sua aplicação reaja às mudanças sem consultar repetidamente a API.

Encontre o conteúdo certo

Necessidade	Conteúdo
Entender como Webhooks funcionam	Introdução - Webhooks
Configurar pela aplicação Asaas	Criar novo Webhook pela aplicação web
Configurar programaticamente	Criar novo Webhook pela API
Implementar o endpoint receptor	Receba eventos do Asaas no seu endpoint de Webhook
Escolher os eventos	Eventos de Webhooks
Tratar eventos duplicados	Como implementar idempotência em Webhooks
Escolher entre envio sequencial e não sequencial	Tipos de envio
Entender quando usar Webhooks em vez de consultas	Polling vs. Webhooks
Investigar falhas de entrega	Logs de Webhooks
Resolver problemas de fila	Fila pausada

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Selecionar os eventos"] --> B["Criar o Webhook"]
    B --> C["Receber o POST"]
    C --> D["Persistir o evento"]
    D --> E["Responder HTTP 200"]
    E --> F["Processar de forma idempotente"]
    F --> G["Atualizar a aplicação"]
    G --> H["Monitorar os logs"]

    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,D,E,F,G validacao
    class H sucesso

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

Regras essenciais

Comportamento	Como tratar
Entrega `at least once`	O mesmo evento pode ser recebido mais de uma vez. Utilize o `id` do evento para implementar idempotência.
Resposta do endpoint	Persista o evento e responda `HTTP 200` rapidamente. Processe regras de negócio de forma assíncrona.
Falha na entrega	O Asaas realiza novas tentativas e pode aplicar penalização à fila.
Falhas consecutivas	Após 15 falhas consecutivas, a fila do Webhook pode ser interrompida.
Retenção	Eventos pendentes permanecem disponíveis por até 14 dias.
Quantidade de Webhooks	Cada conta pode possuir até 10 Webhooks configurados.

⚠️
Atenção
Não processe um evento como se cada entrega fosse única.
Os Webhooks seguem o modelo at least once, portanto sua integração deve suportar reenvios sem duplicar ações.

Escolha os eventos

Cada Webhook pode ser configurado para receber somente os eventos necessários à sua integração.

A página Eventos de Webhooks centraliza as categorias disponíveis e direciona para os eventos específicos de cobranças, assinaturas, transferências, notas fiscais, Checkout, Pix Automático e outros recursos.

Evite configurar eventos que sua aplicação não utiliza.

Prepare o endpoint para Produção

Antes de utilizar Webhooks em Produção:

implemente idempotência;
persista o evento antes de executar processamentos demorados;
responda HTTP 200 rapidamente;
monitore os Logs de Webhooks;
proteja o endpoint com autenticação e regras de rede adequadas.

Se utilizar um authToken, valide o header:

asaas-access-token

Para restrições de rede, consulte IPs oficiais do Asaas.

Quando houver falhas

Comece pelos Logs de Webhooks para identificar o código HTTP, timeout ou erro de comunicação.

A continuidade depende da situação:

Situação	Como seguir
O endpoint começou a falhar	Penalização de filas
A fila foi interrompida	Fila pausada
O problema foi corrigido	Como reativar fila interrompida
Cloudflare retorna `403`	Bloqueio do Firewall na CloudFlare
É necessário configurar allowlist	IPs oficiais do Asaas

As páginas específicas de erros 400, 403, 404, 408, 500, conexão e timeout complementam o troubleshooting quando a causa já estiver identificada.

Próximos passos

Updated 17 days ago

Did this page help you?