feat(evohub): registra webhook inbound no hub durante o link-existing

[pastoriniMatheus]

Empilhada sobre a #2635 (correção de build da EVO-2097) — mergear aquela primeiro; depois esta PR fica só com o commit 9095da7e.

Problema

No canal EvoHub há dois fluxos para plugar um canal do hub numa Instance (ambos disparados pelo manager via rotas /evohub/*):

• POST /evohub/provision (canal novo) → registra o webhook inbound no hub via single-shot do POST /api/v1/channels ✅
• POST /evohub/link-existing (canal já existente no hub) → criava a Instance sem registrar webhook nenhum ❌

Resultado: canal vinculado envia mensagens normalmente (data-plane ${HUB}/meta/*), mas nunca recebe — o hub não tem para onde entregar os eventos e nenhum erro aparece em lado algum. A Instance nasce "surda" silenciosamente.

Implementação

evohub.client.ts — novo ensureChannelWebhook(channelId, webhookUrl) idempotente, com resolução em 3 níveis para nunca duplicar webhooks no hub:

1. Já existe webhook associado ao canal com a mesma URL (não-inactive) → no-op (GET /api/v1/channels/:id/webhooks);
2. Existe webhook do usuário com a mesma URL → associa via POST /api/v1/webhooks/:id/associate (se for all_channels, nem associa — já cobre);
3. Não existe → cria via POST /api/v1/webhooks single-shot com channels: [channelId] e events: [] (vazio = todos os eventos, contrato do hub em webhook_service.go:98). O secret vai junto quando EVOLUTION_HUB_WEBHOOK_SECRET está setado (recipe register-with-own-secret — o hub assina X-Hub-Signature-256 e o verifyHmac do inbound valida).

Suporte: interface HubWebhookInfo, listChannelWebhooks(), listWebhooks(), associateWebhook() e normalização de lista (webhooks | data | array nu).

evohub.controlplane.router.ts — link-existing garante o webhook ANTES de criar a Instance:

const serverUrl = configService.get<HttpServer>('SERVER').URL;
if (serverUrl) {
  try {
    await evoHubClient.ensureChannelWebhook(hub_channel_id, `${serverUrl}/webhook/evohub`);
  } catch (e) {
    return res.status(502).json({
      error: 'failed to register inbound webhook on hub',
      detail: e?.response?.data ?? e?.message,
    });
  }
}

Decisões:

• Webhook antes da Instance: se o hub recusar (quota do plano, API key inválida), o request falha com 502 e nada fica pela metade — retry seguro. Antes, a Instance nasceria surda sem indício.
• SERVER_URL vazio → segue sem webhook: paridade com o provision (que também omite webhook_url nesse caso).

.env.example — documentação de preenchimento das variáveis EvoHub (as variáveis já existiam; faltava orientação): aviso de que o inbound chega em {SERVER_URL}/webhook/evohub e o SERVER_URL precisa ser alcançável pelo hub (host.docker.internal:8080 com hub em Docker), valores típicos de EVOLUTION_HUB_URL (SaaS × local :8086), formato evh_pk_... da API key (obrigatória para /evohub/*) e semântica do WEBHOOK_SECRET (soft mode quando vazio).

Validação

• tsc --noEmit, eslint e npm run build verdes (hooks de pre-commit/pre-push do repo)
• Checklist end-to-end na EVO-2098 (exige hub de pé + API key + SERVER_URL alcançável): link → webhook criado no hub; segundo link → webhook reaproveitado via associate; mensagem inbound chega na Instance; API key inválida → 502 sem Instance criada

Refs EVO-2098

[sourcery-ai]

Sorry @pastoriniMatheus, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[pastoriniMatheus]

Validação end-to-end executada em ambiente local (hub via docker-compose + esta branch): link-existing cria a Instance (201), registra o webhook no hub com secret, não duplica no segundo canal (reuso via associate — 1 webhook, 2 associações), mensagem Meta simulada atravessa hub → /webhook/evohub → HMAC validado → Instance correta por phone_number_id, e API key inválida falha limpa sem criar Instance. Detalhes e evidências no comentário da EVO-2098.

Achado colateral: bug pré-existente de invalidação de cache no hub segura a entrega inbound por até 5min após a associação — registrado como EVO-2099 (fix no repo evolution-hub; não bloqueia esta PR).