Ingress Canônico de Webhook & Forwarder Assíncrono RabbitMQ

1. Contexto Operacional

Provedores de WhatsApp (Evolution API, Zapster) suportam apenas uma única URL de callback por instância. Para eliminar a concorrência e o acoplamento síncrono no banco relacional rocketz.webhooks (~1,3 milhão de registros), o ecossistema centraliza a ingestão na URL canônica agnóstica:

POST https://connect.yzex.com.br/api/integrations/whatsapp/webhook

O servidor atua como Ingress Gateway, persistindo eventos com durabilidade no RabbitMQ e repassando assincronamente para o sistema legado e para o processador de status interno.

2. Topologia AMQP e Retry Loop Escalonado

Componente Nomenclatura Propósito

Topic Exchange Principal

yzex.events

Roteamento pub/sub durável de todos os eventos da plataforma.

Topic Exchange Retry

yzex.events.retry

Roteamento de retries com backoff escalonado por TTL.

Direct Exchange DLX

yzex.events.dlx

Roteamento de mensagens descartadas definitivamente (DLQ).

Fila Principal de Repasse

yzex-connect-whatsapp-legacy-forward-queue

Consumo pelo worker de repasse com prefetch 20.

Filas de Retry com TTL

retry-1m, retry-5m, retry-15m, retry-60m

Dead-letter loop onde a mensagem aguarda o TTL e retorna via DLX para a fila principal.

DLQ Definitiva

yzex-connect-whatsapp-legacy-forward-dlq

Armazenamento permanente de poison pills (4xx) ou retries esgotados.

Fila de Eventos Interna

yzex-connect-whatsapp-events-queue

Atualização assíncrona de connect.whatsapp_instances.

3. Garantias de Engenharia SRE

  1. Stream Bruto Inviolável: O payload original é transmitido em Base64 com hash SHA-256 de integridade, prevenindo corrupção em requisições application/x-www-form-urlencoded ou reordenação JSON.

  2. Autenticação Serviço-a-Serviço (S2S): O repasse ao Supabase legado é assinado via HMAC-SHA256 (x-webhook-signature) com LEGACY_WEBHOOK_HMAC_SECRET segregado e carimbo temporal anti-replay de 5 minutos.

  3. Allowlist Estrita de Headers: Repassa apenas content-type, user-agent, traceparent, x-request-id, x-webhook-signature e x-webhook-timestamp. Headers de rede ou autenticações internas são sanitizados.

  4. Idempotência Compartilhada: Deduplicação no Redis com estados processing → forwarded.

  5. Classificação Semântica e Circuit Breaker: Respostas 2xx recebem ACK; erros 4xx permanentes vão direto à DLQ; 5xx/Timeout entram no retry loop escalonado. 10 falhas consecutivas abrem o circuit breaker por 30 segundos.