Recebendo webhooks com filas de mensagens

Implemente um receiver de webhooks da Malga resiliente usando filas de mensagens AWS SQS para evitar timeouts e garantir processamento assíncrono.

Um erro comum ao integrar webhooks é colocar regras de negócio diretamente no endpoint que recebe os eventos. Isso aumenta o risco de timeouts e falhas de processamento, fazendo com que a Malga interprete a entrega como malsucedida e inicie reentregas desnecessárias.

A abordagem recomendada é separar o recebimento do processamento: o endpoint apenas valida e enfileira o evento, e um worker separado consome a fila e executa a lógica de negócio.

Arquitetura

Malga → seu endpoint (receiver) → fila → worker → sua lógica de negócio
                                     ↓ (em caso de falha)
                                    DLQ

O receiver deve:

1. Receber o POST da Malga
2. Verificar a assinatura do evento (veja Segurança Webhook)
3. Enfileirar o payload
4. Retornar HTTP 200 imediatamente

O worker consome as mensagens da fila e executa as regras de negócio. Se o processamento falhar, a mensagem é retentada automaticamente pela fila e, após o número máximo de tentativas, encaminhada para a DLQ (Dead Letter Queue), garantindo que nenhum evento seja perdido silenciosamente.

Opções de fila

Serviço	Tipo	Observações
AWS SQS	Gerenciado (cloud)	DLQ nativa, fácil integração com outros serviços AWS
Google Cloud Pub/Sub	Gerenciado (cloud)	Suporte a múltiplos subscribers, retenção configurável
Azure Service Bus	Gerenciado (cloud)	Suporte a filas e tópicos, DLQ nativa
RabbitMQ	Self-hosted / gerenciado	Flexível, amplamente adotado, suporte a DLQ via dead-letter exchange
Redis (BullMQ / Sidekiq)	Self-hosted / gerenciado	Simples de operar, ideal para quem já usa Redis na stack