Guida all'integrazione con Make.com

Risposta rapida: usa l’editor visuale di Make.com con un trigger “Custom webhook”. Punta il webhook_url di Surmado a quel trigger, filtra su event = report.completed e su report.product, poi distribuisci a Google Sheets / Slack / Airtable / Notion. Per dati più approfonditi, aggiungi un modulo HTTP che chiama GET https://api.surmado.com/v1/reports/{{1.report.id}} con autenticazione Bearer.

Tempo di lettura: 14 minuti

Prerequisiti

Account Make.com (il piano gratuito va bene per volumi bassi; Core $9/mese per un uso regolare)
Chiave API Surmado (sur_live_...): creala su app.surmado.com → Settings → API Keys
App di destinazione (Google Sheets, Slack, Airtable, Notion e così via)

Requisiti del piano Make

Piano gratuito:

1.000 operations/mese
Limite di 2 scenari
Sufficiente per 1-5 clienti, volume basso

Piano Core ($9/mese):

10.000 operations/mese
Scenari illimitati
Consigliato per un uso regolare

Piano Pro ($16/mese):

10.000 operations + limiti di dati più alti
Variabili personalizzate, esecuzione prioritaria
Per agenzie con 10+ clienti

Lo schema di integrazione

Trigger: “Webhooks → Custom webhook”. Make ti dà un URL univoco.
Configura Surmado perché invii con POST i completamenti dei report a quell’URL tramite webhook_url quando crei un report.
Filtra su event e report.product.
Leggi il payload annidato con la notazione a punti di Make (1.report.summary.presence_score).
(Facoltativo) Modulo HTTP per recuperare dati più approfonditi tramite REST API.
Agisci: scrivi nell’app di destinazione.

Payload di esempio

{
  "event": "report.completed",
  "timestamp": "2026-04-15T12:00:00+00:00",
  "report": {
    "id": "rpt_abc123xyz",
    "token": "SIG-2026-04-A1B2C",
    "product": "signal",
    "status": "completed",
    "tier": "basic",
    "data_url": "https://api.surmado.com/v1/reports/rpt_abc123xyz",
    "pdf_url": "https://api.surmado.com/v1/reports/view/VIEW_TOKEN",
    "summary": {
      "business_name": "Acme Coffee Roasters",
      "presence_score": 34.2,
      "authority_score": 42.7,
      "competitive_rank": 4,
      "top_competitor": "Blue Bottle"
    }
  }
}

I report di Strategy ("product": "solutions") non hanno un oggetto summary, solo report.token e report.pdf_url.

Workflow 1: da AI Visibility a Google Sheets

Moduli dello scenario

Modulo 1: Webhooks: Custom webhook

Aggiungi un nuovo webhook. Make genera un URL come https://hook.eu2.make.com/abc123def456.
Clicca Determine data structure e avvia un report Surmado di prova (vedi l’esempio curl qui sotto) così Make può rilevare la struttura del payload.

Crea il report di prova con:

curl -X POST https://api.surmado.com/v1/reports/signal \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_slug": "acme_corp",
    "url": "https://acme.com",
    "email": "founder@acme.com",
    "industry": "B2B SaaS",
    "location": "United States",
    "persona": "Small business owners",
    "pain_points": "Losing track of customer conversations",
    "brand_details": "Simple CRM with email integration",
    "direct_competitors": "HubSpot, Pipedrive",
    "webhook_url": "https://hook.eu2.make.com/abc123def456"
  }'

Modulo 2: Tools: Filter

Condizione: 1.event Equal to report.completed AND 1.report.product Equal to signal.

Modulo 3: Google Sheets: Add a Row

Associa le colonne:

Date: {{1.timestamp}}
Token: {{1.report.token}}
Business: {{1.report.summary.business_name}}
Presence Score: {{1.report.summary.presence_score}}
Authority Score: {{1.report.summary.authority_score}}
Competitive Rank: {{1.report.summary.competitive_rank}}
Top Competitor: {{1.report.summary.top_competitor}}

Operations usate per esecuzione: 3.

Workflow 2: Site Audit con alert condizionali

Un solo scenario che scrive ogni Site Audit su Google Sheets e avvisa Slack solo quando performance_score < 70.

Modulo 1: Custom webhook (riusa quello del Workflow 1 o creane uno nuovo).

Modulo 2: Filter: 1.event = report.completed AND 1.report.product = scan.

Modulo 3: Google Sheets: Add a Row con i campi di sintesi di Site Audit (seo_score, performance_score, accessibility_score, total_pages, critical_issues_count).

Modulo 4: Router: dividi in due percorsi.

Percorso A (sempre): prosegue fino al completamento.
Percorso B: Filter 1.report.summary.performance_score < 70 → Slack: Create a message.

Modello del messaggio Slack:

:warning: Performance regression on *{{1.report.summary.business_name}}*

Performance: {{1.report.summary.performance_score}} (below 70 threshold)
SEO: {{1.report.summary.seo_score}}
Accessibility: {{1.report.summary.accessibility_score}}
Critical issues: {{1.report.summary.critical_issues_count}}

View report: {{1.report.pdf_url}}

Operations usate per esecuzione: 4-5 a seconda del percorso seguito.

Workflow 3: email di digest di Strategy

I report di Strategy non includono una sintesi. Schema:

Trigger Custom webhook.
Filter: 1.event = report.completed AND 1.report.product = solutions.
Gmail / Email: Send an email con il link al PDF.

Corpo dell’email:

<p>Strategy report <code>{{1.report.token}}</code> has been delivered.</p>
<p><a href="{{1.report.pdf_url}}">View the full report (PDF)</a></p>

Operations: 2.

Recuperare dati più approfonditi

La sintesi del webhook copre la maggior parte delle esigenze. Per dettagli per piattaforma (per esempio la presenza su ChatGPT e Claude) o per i problemi di Site Audit pagina per pagina, aggiungi un modulo HTTP dopo il filtro:

Modulo: HTTP: Make a request

URL: https://api.surmado.com/v1/reports/{{1.report.id}}
Method: GET
Headers:
- Name: Authorization
- Value: Bearer sur_live_YOUR_API_KEY
Parse response: Yes

A quel punto i moduli successivi possono usare {{2.public_intelligence.data.platform_variance.chatgpt.presence_score}} oppure {{2.public_intelligence.data.audit_data.enrichment.content_gaps.executive_summary}}.

Sicurezza: conserva la tua chiave API in una Connection o in una Custom Variable di Make invece di incollarla direttamente nel modulo.

Schemi avanzati

Router per prodotto

Usa un Router dopo il webhook per smistare in base a 1.report.product:

Ramo 1: signal → workflow di AI Visibility
Ramo 2: scan → workflow di Site Audit
Ramo 3: solutions → digest di Strategy

Un solo URL webhook gestisce ogni tipo di report.

Configurazione multi-cliente per agenzie

Usa 1.report.summary.business_name come identificatore del cliente in una ricerca in un Data store per indirizzare ogni cliente alla sua scheda del foglio o alla sua pagina Notion. Crea ogni cliente come brand Surmado una sola volta con POST /v1/brands/ensure, poi riusa il brand_slug in ogni report.

Formati dei token

Prefissi degli Intelligence Token:

AI Visibility: SIG-YYYY-MM-XXXXX (regex: SIG-\d{4}-\d{2}-[A-Z0-9]{5})
Site Audit: SCN-YYYY-MM-XXXXX (regex: SCN-\d{4}-\d{2}-[A-Z0-9]{5})
Strategy: SOL-YYYY-MM-XXXXX (regex: SOL-\d{4}-\d{2}-[A-Z0-9]{5})

I token non scadono. Gli URL di download firmati della REST API sono validi per circa 15 minuti; il magic link pdf_url nei webhook è valido per circa 30 giorni.

Risoluzione dei problemi

Il trigger webhook non parte: controlla che webhook_url sia stato impostato nella chiamata di creazione del report e prova webhook.site come URL di prova per verificare che Surmado invii i payload.

I campi risultano undefined nei moduli successivi: il report potrebbe non avere quel campo valorizzato (per esempio top_competitor è nullo per i brand senza concorrenti identificati), oppure stai guardando un report di Strategy, che non include una sintesi. Verifica il prodotto con 1.report.product.

Il modulo HTTP restituisce 401: la chiave API manca o è malformata. L’header deve essere Authorization: Bearer sur_live_... (compreso Bearer ).

Le operations usate sono più del previsto: Router e filtri contano ciascuno come un’operation a ogni esecuzione. Consolida dove possibile: un solo modulo Google Sheets con valori associati costa meno di più moduli.

Correlati: Guida all’integrazione API | Dati strutturati e Intelligence Token | Integrazione con Zapier | Integrazione con n8n | Integrazione con Notion