Webhooks e eventos

Webhooks permitem que o Asaas comunique à sua aplicação mudanças que acontecem depois da resposta inicial de uma requisição.

Em operações assíncronas, eles são parte central da arquitetura: mantêm o sistema local atualizado conforme pagamentos, cobranças e outras entidades mudam de estado.

Quando utilizar

Implemente Webhooks quando sua integração precisar:

• acompanhar mudanças de estado que acontecem depois da requisição inicial;
• reagir a confirmações, falhas ou outras alterações de uma operação;
• manter o estado local atualizado sem depender exclusivamente de consultas periódicas;
• executar ações de negócio a partir de eventos ocorridos no Asaas;
• identificar e recuperar falhas no processamento de atualizações.

Antes de começar

Antes de implementar o recebimento de Webhooks:

• identifique quais eventos sua integração precisa acompanhar;
• disponibilize um endpoint acessível pelo Asaas;
• defina como os eventos recebidos serão persistidos;
• prepare um mecanismo de processamento separado do recebimento;
• defina como eventos duplicados serão identificados;
• estabeleça como falhas poderão ser reprocessadas e monitoradas.

Como funciona

O endpoint de Webhook deve executar somente o necessário para receber o evento com segurança e confirmar seu recebimento.

O processamento da regra de negócio deve acontecer separadamente.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Receber Webhook"] --> B["Validar requisição"]
    B --> C{"Evento pode ser aceito?"}

    C --> CSim(("Sim"))
    C --> CNao(("Não"))

    CSim --> D["Persistir evento"]
    D --> E["Responder sucesso"]
    E --> F["Processar evento"]
    F --> G{"Processamento concluído?"}

    G --> GSim(("Sim"))
    G --> GNao(("Não"))

    GSim --> H["Atualizar status do evento"]
    GNao --> I["Registrar falha"]
    I --> J["Reprocessar com segurança"]

    CNao --> K["Rejeitar requisição"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef processo fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px
    classDef recuperacao fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-width:2px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B,D,E,F processo
    class C,G decisao
    class H sucesso
    class I,J,K recuperacao

    class CSim,GSim respostaSim
    class CNao,GNao respostaNao

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

A ordem recomendada é:

receber → validar → persistir → responder → processar

Essa separação reduz a dependência entre o tempo de resposta do endpoint e a complexidade da regra de negócio executada a partir do evento.

1. Receba e valide o evento

Ao receber um Webhook, sua aplicação deve primeiro verificar se a requisição pode ser aceita.

Essa etapa deve se limitar às validações necessárias para proteger o endpoint e garantir que o conteúdo possa seguir para persistência.

Evite executar consultas externas, cálculos complexos ou regras de negócio extensas nesse momento.

O objetivo é manter o caminho de recebimento curto e previsível.

2. Persista antes de processar

Depois de validar o recebimento, registre o evento antes de executar a regra de negócio correspondente.

A persistência permite que sua aplicação saiba que o evento chegou mesmo que alguma etapa posterior falhe.

Mantenha informações suficientes para:

• identificar o evento;
• identificar seu tipo;
• relacioná-lo à entidade correspondente;
• registrar quando ele foi recebido;
• acompanhar seu estado de processamento;
• armazenar informações necessárias para diagnóstico e reprocessamento.

Sem essa etapa, uma falha durante o processamento pode fazer com que a aplicação perca o registro de que o evento foi recebido.

3. Responda antes de executar a regra de negócio

Depois de validar e persistir o evento, responda ao Webhook sem aguardar toda a lógica posterior.

Evite manter a requisição aberta enquanto sua aplicação:

• consulta outros sistemas;
• envia notificações;
• executa operações financeiras;
• atualiza múltiplos serviços;
• realiza cálculos ou processamentos extensos.

Essas ações devem ocorrer depois que o recebimento já tiver sido confirmado.

Isso reduz o risco de o tempo de processamento da sua aplicação provocar falhas no recebimento do Webhook.

4. Processe o evento separadamente

Após o recebimento, encaminhe o evento persistido para o mecanismo responsável pela regra de negócio.

Esse processamento pode:

1. recuperar o evento armazenado;
2. identificar a entidade correspondente;
3. verificar o estado atualmente conhecido;
4. avaliar se aquela atualização ainda precisa ser aplicada;
5. executar a regra de negócio;
6. atualizar o estado local;
7. registrar o resultado do processamento.

Essa separação também permite controlar melhor concorrência, retries e falhas temporárias.

5. Trate eventos duplicados

Sua aplicação deve estar preparada para receber o mesmo evento mais de uma vez.

Isso pode acontecer quando uma tentativa anterior não é reconhecida como concluída ou quando há necessidade de reenvio.

Antes de executar novamente uma ação de negócio, verifique se o evento ou seu efeito já foi processado.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Evento disponível para processamento"] --> B{"Evento já foi processado?"}

    B --> BSim(("Sim"))
    B --> BNao(("Não"))

    BSim --> C["Não repetir a ação"]
    BNao --> D["Validar estado atual"]
    D --> E["Executar regra de negócio"]
    E --> F["Registrar como processado"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef processo fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B decisao
    class C,F sucesso
    class D,E processo

    class BSim respostaSim
    class BNao respostaNao

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

Receber o mesmo evento novamente não deve provocar uma nova consequência quando essa consequência já tiver sido aplicada.

Esse cuidado é especialmente importante para ações como:

• liberar produtos ou serviços;
• enviar notificações;
• movimentar estoque;
• executar operações financeiras;
• disparar integrações com outros sistemas.

6. Controle o estado de processamento

O evento também deve possuir um estado interno que permita acompanhar seu ciclo dentro da sua aplicação.

Uma estrutura simples pode diferenciar:

Os nomes podem variar conforme a arquitetura da aplicação. O importante é conseguir distinguir um evento que apenas chegou de um evento cuja regra de negócio já foi concluída.

7. Reprocesse falhas com segurança

Falhas durante o processamento não devem resultar em perda silenciosa do evento.

Quando ocorrer um erro:

• registre a falha;
• mantenha o evento disponível para nova tentativa;
• registre quantas tentativas já ocorreram;
• evite executar novamente efeitos que já tenham sido concluídos;
• identifique situações que precisam de intervenção.

Antes de reprocessar, considere o estado atual da entidade e os efeitos já executados.

Um evento antigo pode estar sendo reprocessado depois que novas atualizações já ocorreram.

Por isso, o reprocessamento não deve simplesmente repetir a lógica anterior sem validar a situação atual.

8. Proteja o endpoint

O endpoint responsável por receber Webhooks deve ser tratado como uma entrada externa da aplicação.

Implemente os mecanismos de autenticação e validação disponíveis para o fluxo utilizado e não exponha informações sensíveis desnecessariamente.

Também evite utilizar o endpoint de Webhook para outras finalidades da aplicação.

A separação facilita:

• controle de acesso;
• monitoramento;
• rastreabilidade;
• aplicação de limites;
• investigação de comportamentos inesperados.

9. Monitore o fluxo

Persistir os eventos permite acompanhar a saúde da integração.

Monitore indicadores como:

• quantidade de eventos recebidos;
• quantidade de eventos com erro;
• eventos aguardando processamento;
• número de tentativas de reprocessamento;
• tempo entre recebimento e processamento;
• aumento inesperado de falhas;
• eventos que permanecem em processamento por tempo excessivo.

O objetivo é identificar problemas antes que eles se transformem em divergências de estado para um volume maior de operações.

Atenção — erros comuns

Evite implementações que:

• executam toda a regra de negócio antes de responder ao Webhook;
• processam o evento antes de persistir seu recebimento;
• dependem de consultas externas para conseguir responder à requisição;
• assumem que cada evento será recebido apenas uma vez;
• executam novamente ações já concluídas ao receber uma duplicidade;
• não diferenciam eventos recebidos, processados e com erro;
• descartam eventos quando ocorre uma falha;
• reprocessam eventos sem verificar o estado atual da entidade;
• não monitoram tempo de resposta nem falhas de processamento.

Confirme sua arquitetura

Antes do go-live, confirme se sua aplicação consegue responder:

• O endpoint executa somente o necessário antes de responder?
• O evento é persistido antes da execução da regra de negócio?
• O processamento acontece separadamente do recebimento?
• Um evento duplicado pode ser recebido sem repetir uma ação indevida?
• Existe um estado interno para acompanhar o processamento?
• Uma falha permanece registrada para investigação?
• Um evento com erro pode ser reprocessado com segurança?
• O estado atual da entidade é considerado antes de um reprocessamento?
• Existem indicadores para acompanhar falhas e atrasos?
• É possível relacionar um problema ao evento e à entidade correspondentes?

Se essas condições não estiverem atendidas, uma falha temporária no recebimento ou processamento poderá gerar perda de atualização ou divergência entre os sistemas.

Boas práticas

• mantenha o endpoint de recebimento simples e rápido;
• valide e persista o evento antes de executar sua regra de negócio;
• responda ao Webhook antes de iniciar processamentos mais pesados;
• processe eventos de forma desacoplada do recebimento;
• projete o processamento para tolerar duplicidades;
• mantenha estados internos para acompanhar cada evento;
• permita reprocessamento seguro de falhas;
• valide o estado atual antes de reaplicar uma atualização antiga;
• monitore falhas, atrasos e eventos pendentes;
• mantenha dados suficientes para rastrear o fluxo de ponta a ponta.

Próximos passos

Depois de estruturar o recebimento e processamento dos eventos, defina como sua integração repetirá operações com segurança quando ocorrerem falhas:

• Retries e idempotência
• Preparação para produção