Regras:
- Criar o webhook no intermediário (Make/n8n/custom)
- Método: POST
- URL pública HTTPS (essa URL será o crmAccessToken no LinkedScope).
- O endpoint deve aceitar header auth (esse valor será o crmSecretToken no LinkedScope).
- O body recebido do LinkedScope é vazio (null/sem payload).
- Implementar validação de auth no intermediário
- Ler req.headers.auth.
- Se diferente do token esperado, retornar 401/403.
- Se válido, seguir para busca no CRM.
- Buscar deals no CRM e mapear para o formato esperado
- Seu fluxo intermediário deve consultar os endpoints do CRM desejado e retornar negócios abertos (open/created date) nos últimos 24 meses
- Montar um array JSON puro (não objeto com deals)
- Retorno obrigatório: HTTP 200 + application/json + […]
- Estrutura esperada do JSON de resposta
- Raiz deve ser array: [ {deal1}, {deal2} ]
- Campos recomendados por deal:
- dealName, dealLink, companyName, createdAt, dealStage, dealValue
- Campos de identificação (fortemente recomendado):
- linkedinCompanyId ou companyUrn / company_urn
- opcional: linkedinCompanyUrl (/company/123 ou /company/slug)
- Status:
- isWon: true | false | null
- Também aceita strings como won/lost/closedwon/closedlost
Exemplo prático:
[
{
"dealId": "D-1001",
"dealName": "Plano Enterprise",
"dealLink": "https://crm.exemplo.com/deals/D-1001",
"pipeline": "Vendas",
"ownerName": "Ana Silva",
"ownerEmail": "[email protected]",
"companyName": "ACME",
"companyDomain": "acme.com",
"linkedinCompanyId": "89482395",
"dealStage": "Proposta enviada",
"dealValue": 15000,
"createdAt": "2025-11-01T10:23:00Z",
"closedAt": null,
"isWon": null
}
]
- Configurar no LinkedScope (Settings > Integrations > Any CRM)
- Campo 1 (trigger/webhook URL): URL do webhook do intermediário.
- Campo 2 (token): segredo compartilhado.
- Salvar. O backend valida chamando o webhook (dummyFetch).
- Validação e sincronização
- Se webhook/auth falhar no save: erro de credencial (CRM Credentials Error).
- Com conexão salva, o LinkedScope usa esse webhook para carregar deals/users/stages.
- Opcional: disparar sync manual via POST /api/v1/crm-sync/invoke (autenticado).
- Checklist de erros comuns
- Retornar { deals: […] } em vez de […] -> incorreto.
- Se não enviar ownerName / ownerEmail / dealStage -> usuários/estágios ficam ruins/vazios.
- URL sem http/https -> bloqueado na UI.
- Token vazio -> integração ANY tende a retornar vazio.
Para o retorno do webhook:
- A resposta precisa ser um array JSON ([ … ]), não objeto.
- Retornar negócios abertos nos últimos 24 meses (2 anos), para melhor experiência
- Tecnicamente o parser aceita deals com campos faltando (ele aplica fallback), então “hard obrigatório por deal” é mínimo.
- Na prática, para funcionar bem, retorne no mínimo:
- dealName, dealLink, companyName, createdAt, dealStage, dealValue
- Muito recomendado:
- id/dealId/deal_id (dedupe)
- linkedinCompanyId ou companyUrn (match melhor)
- ownerName e ownerEmail (owners/listagens)