webhook-processor

Processador de Webhook

Serviço de processamento de webhooks implementando Idempotência, Ordenação Estrita por Entidade e Audit Logging. Construído para demonstrar robustez no tratamento de eventos distribuídos.

Nota de Portfólio: Este projeto prioriza a correção arquitetural, código limpo e a visibilidade dos trade-offs. Serve como uma implementação de referência para lidar com padrões de processamento assíncrono de forma segura.

🏗 Fluxo Lógico

flowchart TD
    In([Requisição Webhook]) --> Validate{Payload Válido?}
    
    Validate -- Não --> R400[400 Bad Request]
    Validate -- Sim --> Idem{Checagem de Idempotência}
    
    Idem -- Duplicado & Processado --> R409[409 Conflict]
    Idem -- Duplicado & Falhou --> Retry[Retry: Reset & Aceitar]
    Idem -- Novo Evento --> Accept[202 Accepted]
    
    Retry --> Queue
    Accept --> Queue
    Queue --> Lock{Adquirir Mutex}
    Lock --> Process[Processamento Sequencial]
    
    Process -- Sucesso --> DB_OK[(DB: PROCESSED + Audit)]
    Process -- Erro --> DB_FAIL[(DB: FAILED + Audit)]

🚀 Funcionalidades Chave

1. Idempotência Robusta

Previne efeitos colaterais duplicados quando provedores enviam o mesmo evento múltiplas vezes.

Mecanismo: Constraint Unique no banco de dados (event_id).
Refinamento: Distingue entre “Já Processado” (Conflito) e “Falha Anterior” (Retry Permitido). Isso evita o problema de “Estado Zumbi” onde eventos falhados bloqueiam retentativas futuras.

2. Ordenação por Entidade (Concurrency Control)

Garante que um OrderCreated seja sempre processado antes de um OrderPaid.

Mecanismo: Mutex/Lock em memória por customer_id.
Objetivo: Permite processamento paralelo entre diferentes clientes, mantendo a sequência estrita para um único cliente.
Segurança: Implementa um padrão de “Queue Safe Promise” para garantir que um evento com falha não trave a fila do cliente permanentemente.

3. Auditabilidade Total

Toda decisão — seja aceita, ignorada, processada ou falhada — é logada permanentemente.

Por quê? Essencial para depurar problemas em produção onde provedores alegam “nós enviamos” mas o estado do sistema discorda.

🛠 Conjunto de tecnologias

Ambiente de execução: Node.js 20+ (TypeScript Strict Mode)
Framework: Express
Banco de Dados: MySQL 8.0 (via Docker)
ORM: Prisma (Esquema e Migrações)
Testes: Jest + Supertest (Mocks de Unidade & Integração)
Validação: Zod
Documentação: Swagger/OpenAPI

⚡ Guia Rápido

1. Configurar o ambiente

cp .env.example .env

2. Iniciar Infraestrutura

docker-compose up -d

3. Instalar & Migrar

npm install
npm run db:migrate

4. Rodar Localmente

npm run dev
# Swagger Docs at http://localhost:3000/api-docs

⚠️ Limitações Conhecidas (Trade-offs Arquiteturais)

Esta arquitetura faz trade-offs explícitos pela simplicidade e consistência em um ambiente de nó único (single-node).

Restrição	Implicação	Solução de Produção (Escala)
Bloqueios na memória	A expansão para múltiplas instâncias quebra as garantias de ordenação.	Bloqueio do Redis (Redlock) ou particionamento do Kafka (mensagens com chave).
Sem fila de mensagens não entregues	Os eventos com falha permanecem `FAILED` no banco de dados.	Tabela separada `DLQ` + Mecanismo de repetição.
Gravações síncronas no banco de dados	Maior latência no recebimento de solicitações.	Desacoplar a ingestão (SQS/RabbitMQ) do armazenamento.

👨‍💻 Autor

Gérson Resplandes
Engenheiro Backend focado em Sistemas Distribuídos & Confiabilidade.