Guida all'integrazione con Notion

Risposta rapida: non esiste un’integrazione diretta tra Surmado e Notion. Collega i due con Zapier, Make, n8n o un piccolo script personalizzato. Ricevi il webhook report.completed di Surmado, poi chiama l’azione “Create database item” di Notion con i campi di report.summary.

Tempo di lettura: 10 minuti

---

Lo schema

1. Trigger: Surmado invia un payload report.completed a un endpoint webhook (Catch Hook di Zapier, Custom Webhook di Make, Webhook di n8n o il tuo server).
2. Leggi report.summary per le metriche curate. Per AI Visibility sono presence_score, authority_score, competitive_rank e così via. Per Site Audit sono seo_score, performance_score, accessibility_score, critical_issues_count e l’oggetto quick_wins. I report di Strategy non includono una sintesi: usa solo report.pdf_url e report.token.
3. Crea un elemento nel database Notion con i valori delle proprietà associati ai campi del payload.
4. (Facoltativo) Arricchisci con una chiamata REST API a GET /v1/reports/{report_id} se ti servono dati più approfonditi, come public_intelligence.data.platform_variance o public_intelligence.data.audit_data.enrichment.

Imposta il percorso del webhook passando webhook_url quando crei un report Surmado:

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://your-webhook-endpoint.example.com/surmado"
  }'

---

Schemi di database consigliati

Report AI Visibility

Proprietà	Tipo	Campo del payload
Title	Title	report.summary.business_name
Token	Text	report.token
Report ID	Text	report.id
Presence Score	Number	report.summary.presence_score
Authority Score	Number	report.summary.authority_score
Competitive Rank	Number	report.summary.competitive_rank
Top Competitor	Text	report.summary.top_competitor
Report Date	Date	timestamp
PDF	URL	report.pdf_url
Status	Select	derivato da presence_score, vedi sotto

Puoi calcolare la proprietà Status di tipo select con una tabella di corrispondenza:

• presence_score < 30 → At Risk
• 30 <= presence_score < 60 → Needs Work
• presence_score >= 60 → Leading

Report Site Audit

Proprietà	Tipo	Campo del payload
Title	Title	report.summary.business_name oppure URL
Token	Text	report.token
Report ID	Text	report.id
SEO Score	Number	report.summary.seo_score
Performance Score	Number	report.summary.performance_score
Accessibility Score	Number	report.summary.accessibility_score
Total Pages	Number	report.summary.total_pages
Critical Issues	Number	report.summary.critical_issues_count
Report Date	Date	timestamp
PDF	URL	report.pdf_url

Report Strategy

I report di Strategy espongono nel webhook solo il token e l’URL del PDF. Uno schema essenziale:

Proprietà	Tipo	Campo del payload
Title	Title	derivato (brand + data)
Token	Text	report.token
Report ID	Text	report.id
Report Date	Date	timestamp
PDF	URL	report.pdf_url

---

Configurazione con Zapier (consigliata)

L’integrazione Notion di Zapier ha un’azione “Create Database Item” che si associa bene al payload del webhook.

1. Crea uno Zap: Webhooks by Zapier → Catch Hook (copia l’URL che ti viene dato).
2. Configura un report Surmado con webhook_url impostato su quell’URL.
3. Filtro: event = report.completed AND report__product = signal (oppure scan).
4. Azione: Notion → Create Database Item. Associa i campi usando l’output del webhook (Zapier appiattisce le chiavi annidate con il doppio trattino basso: report__summary__presence_score).

Guida completa con esempi di Zap: Guida all’integrazione con Zapier.

---

Script personalizzato (senza Zapier)

Se preferisci il codice, esegui un piccolo server che accetta il webhook di Surmado e chiama direttamente l’API di Notion.

Esempio in Node.js

const express = require('express');
const { Client } = require('@notionhq/client');

const notion = new Client({ auth: process.env.NOTION_API_KEY });
const DATABASE_ID = process.env.NOTION_DATABASE_ID;

const app = express();
app.use(express.json());

app.post('/surmado-webhook', async (req, res) => {
  const { event, report, timestamp } = req.body;
  if (event !== 'report.completed' || report.product !== 'signal') {
    return res.status(200).end();
  }

  await notion.pages.create({
    parent: { database_id: DATABASE_ID },
    properties: {
      'Name': { title: [{ text: { content: report.summary.business_name || report.token } }] },
      'Token': { rich_text: [{ text: { content: report.token } }] },
      'Report ID': { rich_text: [{ text: { content: report.id } }] },
      'Presence Score': { number: report.summary.presence_score ?? null },
      'Authority Score': { number: report.summary.authority_score ?? null },
      'Competitive Rank': { number: report.summary.competitive_rank ?? null },
      'Top Competitor': { rich_text: [{ text: { content: report.summary.top_competitor || '' } }] },
      'Report Date': { date: { start: timestamp } },
      'PDF': { url: report.pdf_url || null }
    }
  });

  res.status(200).end();
});

app.listen(process.env.PORT || 3000);

Verifica la firma del webhook prima di fidarti del payload: l’algoritmo HMAC-SHA256 è descritto nella Guida all’integrazione API.

---

Arricchire le pagine Notion con dati più approfonditi

La sintesi del webhook copre la maggior parte delle esigenze. Se vuoi dettagli per piattaforma (per esempio ChatGPT e Claude), chiama la REST API dopo la creazione della pagina Notion:

curl -s https://api.surmado.com/v1/reports/{report_id} \
  -H "Authorization: Bearer sur_live_YOUR_API_KEY" \
  | jq '.public_intelligence.data.platform_variance'

Poi aggiorna la pagina Notion con un blocco di testo formattato che contiene i punteggi per piattaforma.

---

Risoluzione dei problemi

Notion crea la pagina ma le proprietà sono vuote: il tipo di campo in Notion deve corrispondere al payload. Numeri come presence_score richiedono una proprietà Number, non Rich Text. Controlla che il tipo di ogni proprietà corrisponda alla tabella qui sopra.

Il webhook parte ma la chiamata a Notion fallisce: Surmado riprova 3 volte sulle risposte 5xx, poi smette. Controlla i log del server, correggi l’errore, poi recupera di nuovo a mano tramite REST API i report che sono andati persi.

I report di Strategy non mostrano punteggi: è normale. Strategy non espone public_intelligence; sono disponibili solo report.token e report.pdf_url.

---

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