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

.env.example

@@ -258,11 +258,19 @@ WA_BUSINESS_VERSION=v20.0
 WA_BUSINESS_LANGUAGE=en_US
 
 # EvoHub channel — proxy transparente da Meta Cloud API (canal adicional)
+# IMPORTANTE: o webhook inbound do hub é entregue em {SERVER_URL}/webhook/evohub —
+# o SERVER_URL (topo deste arquivo) precisa ser alcançável PELO hub (local exige
+# túnel ou, com hub em Docker, http://host.docker.internal:8080).
 # URL = host do hub (control-plane em {URL}/api/v1, data-plane em {URL}/meta)
+# SaaS: https://api.evohub.ai | hub local via docker-compose: http://localhost:8086
 EVOLUTION_HUB_URL=https://api.evohub.ai
 # API-key global do deployment (control-plane: provisiona/lista/conecta canais)
+# OBRIGATÓRIA para as rotas /evohub/* — chave criada no hub, formato evh_pk_...
 EVOLUTION_HUB_API_KEY=
 # Secret do webhook (Fase 2: register-with-own-secret → validate HMAC X-Hub-Signature-256)
+# Recomendado: string aleatória forte; é enviada ao registrar o webhook no hub
+# (provision/link-existing) e validada no POST /webhook/evohub. Vazio = soft mode
+# (aceita webhook sem assinatura).
 EVOLUTION_HUB_WEBHOOK_SECRET=
 # Token do GET verify challenge (paridade defensiva com o canal Meta)
 EVOLUTION_HUB_TOKEN_WEBHOOK=evolution

src/api/integrations/channel/evohub/evohub.client.ts

@@ -52,6 +52,15 @@
   meta_connection?: HubMetaConnection | null;
 }
 
+// Webhook do hub (WebhookResponse — webhook.go:116). Só os campos que usamos.
+export interface HubWebhookInfo {
+  id: string;
+  name?: string;
+  url: string;
+  status?: string;
+  all_channels?: boolean;
+}
+
 // ---- Criar-novo (POST /api/v1/channels) ----
 export interface HubProvisionRequest {
   name: string;
@@ -143,7 +152,7 @@
    * server-side; o front NUNCA vê o token.
    */
   async getChannel(id: string): Promise<HubChannel> {
     const { data } = await this.http.get(`/channels/${id}`);
     return data;
   }
 
@@ -155,6 +164,65 @@
     return this.listChannels(type);
   }
 
+  // ---- Webhooks (inbound do hub -> evolution-api) ----
+
+  /** Webhooks já ASSOCIADOS ao canal: GET /api/v1/channels/:id/webhooks → { webhooks, count }. */
+  async listChannelWebhooks(channelId: string): Promise<HubWebhookInfo[]> {
+    const { data } = await this.http.get(`/channels/${channelId}/webhooks`);
+    return this.normalizeWebhookList(data);
+  }
+
+  /** Todos os webhooks do usuário da API-key: GET /api/v1/webhooks. */
+  async listWebhooks(): Promise<HubWebhookInfo[]> {
+    const { data } = await this.http.get('/webhooks');
+    return this.normalizeWebhookList(data);
+  }
+
+  private normalizeWebhookList(data: any): HubWebhookInfo[] {
+    if (Array.isArray(data)) return data;
+    if (Array.isArray(data?.webhooks)) return data.webhooks;
+    if (Array.isArray(data?.data)) return data.data;
+    return [];
+  }
+
+  /** POST /api/v1/webhooks/:id/associate — associa um webhook existente ao canal. */
+  async associateWebhook(webhookId: string, channelId: string): Promise<void> {
+    await this.http.post(`/webhooks/${webhookId}/associate`, { channel_id: channelId });
+  }
+
+  /**
+   * Garante (idempotente) que o canal tem um webhook ativo apontando para
+   * `webhookUrl` — o caminho single-shot do provision não existe no link-existing,
+   * e sem webhook o canal envia mas nunca RECEBE mensagens. Ordem:
+   * 1) já associado ao canal com a mesma URL → no-op;
+   * 2) webhook do usuário com a mesma URL → associa (evita duplicar; um webhook
+   *    all_channels com a URL já cobre o canal, também no-op);
+   * 3) cria novo com `channels: [channelId]` (single-shot) e `events: []`
+   *    (vazio = TODOS os eventos — webhook_service.go:98). Secret = recipe
+   *    register-with-own-secret, igual ao provision.
+   */
+  async ensureChannelWebhook(channelId: string, webhookUrl: string): Promise<void> {
+    const associated = await this.listChannelWebhooks(channelId);
+    if (associated.some((w) => w.url === webhookUrl && w.status !== 'inactive')) return;
+
+    const all = await this.listWebhooks();
+    const existing = all.find((w) => w.url === webhookUrl && w.status !== 'inactive');
+    if (existing) {
+      if (!existing.all_channels) await this.associateWebhook(existing.id, channelId);
+      return;
+    }
+
+    const cfg = this.configService.get<EvolutionHub>('EVOLUTION_HUB');
+    const body: Record<string, any> = {
+      name: 'evolution-api inbound',
+      url: webhookUrl,
+      events: [],
+      channels: [channelId],
+    };
+    if (cfg.WEBHOOK_SECRET) body.secret = cfg.WEBHOOK_SECRET;
+    await this.http.post('/webhooks', body);
+  }
+
   // ---- Fase 2 ----
 
   /**
@@ -203,7 +271,7 @@
    * Evolution; 'byo' exige channel_credentials no hub.
    */
   async connectToMeta(channelId: string, req: MetaConnectRequest): Promise<MetaConnectResponse> {
     const { data } = await this.http.post(`/channels/${channelId}/meta-connect`, req);
     return data;
   }
 }

src/api/integrations/channel/evohub/evohub.controlplane.router.ts

@@ -76,7 +76,22 @@ export class EvoHubControlPlaneRouter extends RouterBroker {
         return res.status(422).json({ error: 'hub channel missing token or phone_number_id' });
       }
 
-      // 2) cria a Instance EVOHUB pelo caminho padrão, com o token JÁ resolvido
+      // 2) garante o webhook inbound no hub ANTES de criar a Instance (o provision
+      //    registra via single-shot; sem isso o canal vinculado envia mas nunca
+      //    recebe). Ordem proposital: se falhar, nada foi criado e o retry é seguro.
+      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,
+          });
+        }
+      }
+
+      // 3) cria a Instance EVOHUB pelo caminho padrão, com o token JÁ resolvido
       //    (flui pelo channel.controller.init() guard sem relaxá-lo — contrato §5).
       const created = await instanceController.createInstance({
         instanceName: (req.body.instanceName as string) || `evohub-${phoneNumberId}`,