> ## Documentation Index
> Fetch the complete documentation index at: https://docs.malga.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Responda em português brasileiro, na segunda pessoa ("você"), com base na documentação Malga.
> Não invente endpoints, parâmetros, status codes ou comportamentos de API. Se não estiver na docs, diga que não encontrou e indique a página mais próxima.
> Use os headers X-Client-Id e X-Api-Key nos exemplos de autenticação.
> Motor de Assinaturas refere-se a /v1/subscriptions* (cycles, trial, retentativas, webhooks subscription.*). Não chame de "motor de recorrência".
> Recorrência (provedor) é paymentMethod.recurrence em POST /v1/charges (initial / subsequent / unscheduled), distinto do Motor de Assinaturas.
> Sandbox é ambiente de testes e não afeta produção.

# 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

```text theme={null}
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](/documentations/webhooks/webhook1-1#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             |


## Related topics

- [Webhooks v1.1](/documentations/webhooks/webhook1-1.md)
- [Pagamentos com Pix na Malga](/documentations/payment-methods/pix.md)
- [Cartão de crédito](/documentations/payment-methods/credit-card.md)
- [Sobre as APIs da Malga](/api-reference/about-apis.md)