⚙️ Background Webhook — Processamento de Leads em Alta Escala

Uma solução robusta atuando como Middleware de Integração entre CRM (Segline), Sistemas Telefônicos (Asterisk/Isabel) e APIs de enriquecimento de dados (Finnecta). Projetada para resolver um gargalo crítico: processar dezenas de milhares de leads simultaneamente sem travar os sistemas principais.

🚀 O Problema Resolvido

Sistemas tradicionais processam importações de forma síncrona, causando timeouts em requisições HTTP e travamento de banco de dados (Table Locks) ao tentar inserir milhares de linhas linha a linha.

O Background_Webhook resolve isso recebendo a requisição, enfileirando os dados em memória e liberando o cliente imediatamente (latência de ~50ms), enquanto processa tudo em background com paralelismo hiper-otimizado.

---

🏗️ Arquitetura do Sistema

A aplicação utiliza o padrão Async Queue-Based Processing através de System.Threading.Channels e BackgroundServices nativos do .NET.

graph TD
    subgraph Entradas [📥 Fontes de Dados]
        CRM[CRM Segline]
        Discadora[Integrações Asterisk / Isabel]
    end

    subgraph API [⚙️ Webhook API middleware]
        Controller[Controllers <br/> Recebem pacotes de até 50k leads]
        Fila[System.Threading.Channels <br/> Fila Bounded Limitada a 100]
        Workers[BackgroundServices <br/> Processamento Assíncrono]
        Cache[IMemoryCache <br/> Rastreio de Progresso com TTL]
    end

    subgraph Destinos [🚀 Processamento Paralelo]
        Finnecta[API Finnecta <br/> Enriquecimento em lote]
        DB[(SQL Server / MySQL <br/> SqlBulkCopy + Procedures)]
        Asterisk[Integrações Externas <br/> POST Asterisk/Isabel]
    end

    CRM --> Controller
    Discadora --> Controller
    Controller --> Fila
    Controller --> Cache
    Fila --> Workers
    Workers --> Finnecta
    Workers --> DB
    Workers --> Asterisk

Loading

🔄 Fluxo de Importação e Enriquecimento (Exemplo Real)Como o sistema processa um lote gigante de leads enviados pelo CRM:

sequenceDiagram

    actor CRM
    participant API as Webhook Controller
    participant Fila as Channel (Fila Interna)
    participant Worker as Background Service
    participant Finnecta as API Finnecta
    participant DB as Banco de Dados
    
    CRM->>API: POST /importacaoleads (Lote: 50.000 leads)
    API->>Fila: Enfileira Pacote Instantaneamente
    API-->>CRM: 202 Accepted { idSessao } (Latência: ~50ms)
    
    Note over Worker: Inicia processamento assíncrono controlado
    Fila->>Worker: Dequeue (Consome pacote da fila)
    
    Worker->>Finnecta: Busca Dados Paralela (MaxDegreeOfParallelism = 15)
    Finnecta-->>Worker: Retorna Enriquecimento (Nome, Renda, Endereço)
    
    Worker->>Worker: Converte para DataTable Estruturado
    Worker->>DB: SqlBulkCopy (TableLock mode)
    DB-->>Worker: 50k Inserts concluídos em ~15s
    
    Worker->>DB: Executa Stored Procedure de Distribuição

Loading

Note over CRM,API: Durante todo o processo, o CRM consulta
GET /progresso/{idSessao} em tempo real via Cache.

⚡ Estratégias de Otimização e Benchmarks

A aplicação implementa táticas avançadas de performance do ecossistema .NET:

• SqlBulkCopy: Resolve o gargalo de inserts unitários e timeouts HTTP (30s+). Impacto: Redução de 40s para 0,5s (1k leads), inserindo 50.000 leads em ~15 a 20s.

• SemaphoreSlim (Max 4): Previne que múltiplos workers saturem as conexões do SQL Server (Pool Starvation). Impacto: Paralelismo controlado, limitando as execuções pesadas no BD a 4 por vez e mantendo a estabilidade.

• System.Threading.Channels: Evita memory leaks causados por filas infinitas. Impacto: Criação de backpressure com canal limitado (Bounded 100), pausando o recebimento se a fila encher.

• Parallel.ForEachAsync (Max 15): Soluciona a lentidão de consultas de enriquecimento 1 a 1 (que levariam mais de 8 minutos para 5k leads). Impacto: Tempo reduzido de 500s para 35s no enriquecimento de 5.000 CPFs via API externa.

• IMemoryCache: Resolve a perda de visibilidade sobre o status do processamento assíncrono. Impacto: Respostas em <1ms para endpoints de tracking, com expiração automática (TTL de 2h) liberando memória RAM.

• DbConnectionFactory: Elimina o forte acoplamento com um único SGBD. Impacto: Multiplexação e estrutura preparada para operar tanto em SQL Server quanto em MySQL.

🔌 Principais Endpoints

• POST /api/importacaoleads/receber Recebe grandes volumes (500 a 50.000+) do CRM para enriquecimento opcional e importação via Bulk Insert.

Retorna 202 Accepted quase instantaneamente.

• GET /api/importacaoleads/progresso/{idSessao}

Consulta o IMemoryCache e retorna porcentagem, status e itens processados em tempo real.

• POST /api/filadiscador/receber

Recebe e formata leads, realizando a inserção rápida no banco e disparando os dados simultaneamente (Multiplexação) para a API final da discadora (Asterisk/Isabel).

🐳 Como Executar Localmente

1.Configuração (appsettings.json) Configure suas strings de conexão na raiz do projeto:JSON

"ConnectionStrings": {
  "DefaultConnection": "Server=localhost;Database=BackgroundDB;User Id=sa;Password=SuaSenha;"
}

2. Rodando via CLI (.NET CLI)

Restaura dependências e compila

dotnet build

Executa o projeto Web API

dotnet run --project src/Background_Webhook/Background_Webhook.csproj

Acesso local ao Swagger

Navegue para: http://localhost:5000/swagger

3. Execução dos Testes (xUnit + Moq)O projeto conta com testes unitários cobrindo o comportamento assíncrono das filas e lógicas de Controller.Bashdotnet test src/Background_Webhook.Tests/Background_Webhook.Tests.csproj

Este projeto foi desenhado focando em resiliência extrema, onde a queda de uma integração externa ou pico de acessos não derruba a importação central.

👨‍💻 Autor

Jeferson Pimentel Sena Full Stack Engineer

💼 LinkedIn

📱 WhatsApp