Você atende vários clientes e não quer reinventar a integração a cada projeto. A ideia desta página é essa: transformar a implantação da API do GS Engage em um processo repetível. O que muda de um cliente para outro é quase sempre só a chave de acesso; o resto do fluxo você padroniza.

Esta é a trilha da Camila, que cuida de operação e tecnologia para uma carteira de clientes. Se esse é o seu papel, o objetivo aqui é entregar rápido, sem retrabalho e sem sustos em produção.

O segredo de reaproveitar código entre clientes é isolar o que muda. Na prática, quase tudo é igual — a URL base, os caminhos, o formato dos dados. O que muda por cliente é a apiKey (a chave de acesso, com cerca de 40 caracteres, que autentica cada conta).

Pense na sua integração como um único código com a chave parametrizada por conta:

// Uma configuração por cliente — só a chave muda
const clientes = {
  "cliente-a": { apiKey: process.env.GSENGAGE_KEY_CLIENTE_A },
  "cliente-b": { apiKey: process.env.GSENGAGE_KEY_CLIENTE_B },
};

const BASE_URL = "https://api.gsengage.com/api/v1";

function url(cliente, caminho) {
  const { apiKey } = clientes[cliente];
  return `${BASE_URL}${caminho}?apiKey=${apiKey}`;
}

Com isso, o mesmo fluxo serve para qualquer cliente: você troca só a etiqueta da conta e as chaves ficam guardadas fora do código, em variáveis de ambiente.

Use este checklist a cada novo cliente. Ele fica salvo no seu navegador, então você pode marcar item por item durante a implantação.

A ordem abaixo evita retrabalho: você só cria leads depois de ter certeza que a chave funciona, e só liga webhooks depois que os leads já entram na Cadência.

graph LR
A["1. Autenticar<br/>(validar a apiKey)"] --> B["2. Criar leads"]
B --> C["3. Colocar na Cadência<br/>(iniciar prospecção)"]
C --> D["4. Registrar webhooks"]
D --> E["5. Validar ponta a ponta"]

curl "https://api.gsengage.com/api/v1/custom-fields?apiKey=SUA_CHAVE"

curl -X POST "https://api.gsengage.com/api/v1/leads?apiKey=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Souza",
    "company": "Souza Consultoria",
    "emails": [{ "value": "maria@souza.com", "label": "Trabalho" }],
    "mobiles": [{ "value": "+5511999998888", "label": "WhatsApp" }]
  }'

curl "https://api.gsengage.com/api/v1/routines?apiKey=SUA_CHAVE"

curl -X POST "https://api.gsengage.com/api/v1/routines/SEU_ROUTINE_ID/lead?apiKey=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "leadId": "ID_DO_LEAD" }'

curl -X POST "https://api.gsengage.com/api/v1/webhooks?apiKey=SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Avisos de venda - Cliente A",
    "url": "https://sua-agencia.com/hooks/cliente-a",
    "events": ["prospection.won", "prospection.lost"]
  }'

Estes quatro padrões valem para todos os clientes. Adote-os uma vez no seu código e você elimina a maior parte dos problemas de produção.

Como conferir a assinatura do webhook

Cada entrega chega no seu endereço como um POST com este envelope:

{
  "id": "evt_123",
  "test": false,
  "event": "prospection.won",
  "data": { },
  "retries": 0,
  "manualRetries": 0,
  "createdAt": "2026-07-17T12:00:00Z"
}

A entrega vem assinada com HMAC SHA-256 (um cabeçalho de assinatura calculado a partir do corpo da mensagem e do seu secret). Do seu lado, você recalcula a assinatura e compara: se baterem, o aviso é autêntico.

import crypto from "crypto";

function assinaturaConfere(corpoBruto, assinaturaRecebida, secret) {
  const esperada = crypto
    .createHmac("sha256", secret)
    .update(corpoBruto)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(esperada),
    Buffer.from(assinaturaRecebida)
  );
}

Nem todo cliente tem equipe de desenvolvimento — e nem toda integração precisa de código. Para os casos simples (levar um lead de um formulário para a Cadência, ou avisar o time no chat quando uma venda fecha), você entrega em uma tarde usando ferramentas de automação.

O que mais gera retrabalho em implantações de agência: