Tipos de envio

Antes de configurar um webhook, é possível definir o tipo de envio que será utilizado. Essa configuração influencia diretamente a ordem em que os eventos serão recebidos, o tempo de processamento e o comportamento da integração em cenários com alto volume de notificações.

Os Webhooks do Asaas oferecem dois tipos de envio:

Sequencial
Não Sequencial

A escolha do tipo de envio deve considerar a necessidade de preservar a ordem dos eventos e a capacidade de processamento da sua aplicação.

Qual a diferença entre os tipos de envio?

No envio Sequencial, os eventos são enviados respeitando a ordem em que ocorreram.

No envio Não Sequencial, os eventos podem ser enviados simultaneamente, sem garantir ordem entre eles, proporcionando maior vazão e menor tempo de entrega.

Independentemente do tipo de envio escolhido, os Webhooks do Asaas seguem o modelo at least once, ou seja, um mesmo evento pode ser reenviado em caso de falha na comunicação. Por esse motivo, é recomendado que a aplicação implemente mecanismos de idempotência para evitar processamentos duplicados.

Envio Sequencial

O envio Sequencial é recomendado quando a ordem dos eventos é importante para a lógica da aplicação.

Um exemplo comum ocorre em cobranças, nas quais uma mesma entidade pode passar por diferentes estados durante seu ciclo de vida.

PAYMENT_CREATED
↓
PAYMENT_OVERDUE
↓
PAYMENT_CONFIRMED
↓
PAYMENT_RECEIVED

Nesse cenário, manter a ordem dos eventos é importante para garantir a consistência do processamento.

No exemplo acima, podemos observar que os eventos de uma mesma cobrança são enviados respeitando a sequência em que ocorreram. Dessa forma, a aplicação consegue identificar corretamente que o pagamento foi realizado após o vencimento.

Quando utilizar o envio Sequencial

O envio Sequencial é recomendado para:

Cobranças;
Assinaturas;
Fluxos que dependem da ordem dos eventos;
Integrações que executam regras de negócio diferentes para cada status;
Processos que necessitam de rastreabilidade completa da jornada da entidade.

Envio Não Sequencial

No envio Não Sequencial, os eventos são enviados sem necessidade de aguardar a conclusão dos eventos anteriores.

Isso permite maior paralelismo e uma entrega mais rápida das notificações.

Como os eventos podem ser processados simultaneamente, não há garantia de ordem entre diferentes notificações.

Esse modo é recomendado quando a aplicação recebe poucos eventos por entidade ou quando a sequência dos eventos não interfere na lógica de negócio.

Por exemplo, um webhook utilizado apenas para acompanhar transferências concluídas ou canceladas normalmente recebe apenas um evento relevante por operação, não sendo necessário preservar a ordem dos envios.

Quando utilizar o envio Não Sequencial

O envio Não Sequencial é recomendado para:

Eventos independentes entre si;
Integrações com alto volume de notificações;
Cenários onde a ordem dos eventos não é relevante;
Processamentos assíncronos;
Aplicações com múltiplos workers ou filas paralelas.

Comportamentos importantes

Independentemente do tipo de envio escolhido:

Os eventos podem ser reenviados em caso de falha na comunicação;
Um mesmo evento pode ser recebido mais de uma vez;
A aplicação deve responder com HTTP 200 após processar ou persistir o evento;
É recomendado implementar idempotência para evitar processamentos duplicados;
Eventos que retornam erro ou timeout podem causar penalização ou interrupção da fila;
O processamento assíncrono é recomendado para reduzir o tempo de resposta do endpoint.

Impactos operacionais

Envio Sequencial

Vantagens

Preserva a ordem dos eventos;
Facilita a implementação de regras dependentes de estado;
Simplifica auditoria e rastreabilidade.

Desvantagens

Menor vazão;
Um evento lento pode atrasar os próximos;
Maior sensibilidade a falhas do endpoint.

Envio Não Sequencial

Vantagens

Maior throughput;
Menor latência;
Melhor aproveitamento de processamento paralelo.

Desvantagens

Não garante ordem entre eventos;
Requer maior cuidado no tratamento da lógica da aplicação;
Torna a idempotência ainda mais importante.

Boas práticas

📘
Recomendamos

Utilizar envio Sequencial quando a ordem dos eventos for importante.
Utilizar envio Não Sequencial em integrações de alto volume e eventos independentes.
Persistir os eventos antes do processamento.
Processar eventos de forma assíncrona.
Implementar idempotência para evitar duplicidades.
Monitorar falhas e timeouts do endpoint.
Utilizar os Logs de Webhooks para auditoria e troubleshooting.

Próximos passos

Após escolher o tipo de envio, recomendamos consultar: