Guide d'intégration Notion

Réponse rapide : il n’existe pas d’intégration directe entre Surmado et Notion. Reliez les deux avec Zapier, Make, n8n ou un petit script personnalisé. Recevez le webhook report.completed de Surmado, puis appelez l’action « Create database item » de Notion avec les champs de report.summary.

Temps de lecture : 10 minutes

---

Schéma

1. Déclencheur : Surmado envoie un payload report.completed à un point d’accès webhook (Catch Hook de Zapier, Custom Webhook de Make, Webhook de n8n ou votre propre serveur).
2. Lisez report.summary pour obtenir les métriques sélectionnées. Pour AI Visibility, ce sont presence_score, authority_score, competitive_rank, etc. Pour Site Audit, ce sont seo_score, performance_score, accessibility_score, critical_issues_count et l’objet quick_wins. Les rapports Strategy n’incluent pas de résumé : utilisez uniquement report.pdf_url et report.token.
3. Créez un élément de base Notion avec les valeurs de propriétés issues du payload.
4. (Facultatif) Enrichissez avec un appel à l’API REST GET /v1/reports/{report_id} si vous avez besoin de données plus détaillées comme public_intelligence.data.platform_variance ou public_intelligence.data.audit_data.enrichment.

Mettez en place le chemin du webhook en indiquant webhook_url lorsque vous créez un rapport 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"
  }'

---

Schémas de base recommandés

Rapports AI Visibility

Propriété	Type	Champ du 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	dérivé de presence_score ci-dessous

Une propriété Status de type Select peut être calculée avec une table de correspondance :

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

Rapports Site Audit

Propriété	Type	Champ du payload
Title	Title	report.summary.business_name ou 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

Rapports Strategy

Les rapports Strategy ne transmettent que le token et l’URL du PDF par le webhook. Un schéma minimal :

Propriété	Type	Champ du payload
Title	Title	dérivé (marque + date)
Token	Text	report.token
Report ID	Text	report.id
Report Date	Date	timestamp
PDF	URL	report.pdf_url

---

Configuration avec Zapier (recommandé)

L’intégration Notion de Zapier propose une action « Create Database Item » qui correspond bien au payload du webhook.

1. Créez un Zap : Webhooks by Zapier → Catch Hook (copiez l’URL fournie).
2. Configurez un rapport Surmado avec webhook_url réglé sur cette URL.
3. Filtre : event = report.completed AND report__product = signal (ou scan).
4. Action : Notion → Create Database Item. Associez les champs à partir de la sortie du webhook (Zapier aplatit les clés imbriquées avec un double tiret bas : report__summary__presence_score).

Pas à pas complet avec des exemples de Zaps : Guide d’intégration Zapier.

---

Script personnalisé (sans Zapier)

Si vous préférez le code, faites tourner un petit serveur qui accepte le webhook Surmado et appelle directement l’API de Notion.

Exemple 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);

Vérifiez la signature du webhook avant de faire confiance au payload. Consultez le Guide d’intégration de l’API pour l’algorithme HMAC-SHA256.

---

Enrichir les pages Notion avec des données plus détaillées

Le résumé du webhook couvre la plupart des besoins. Si vous voulez des détails par plateforme (par exemple ChatGPT et Claude), appelez l’API REST après la création de la page 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'

Mettez ensuite la page Notion à jour avec un bloc de texte enrichi contenant les scores par plateforme.

---

Dépannage

Notion crée la page mais les propriétés sont vides : le type du champ dans Notion doit correspondre au payload. Les nombres comme presence_score demandent une propriété Number, pas Rich Text. Vérifiez que le type de chaque propriété correspond au tableau ci-dessus.

Le webhook se déclenche mais l’appel à Notion échoue : Surmado réessaie 3 fois sur les réponses 5xx, puis abandonne. Consultez les journaux de votre serveur, corrigez le bug, puis récupérez manuellement via l’API REST les rapports qui ont été perdus.

Les rapports Strategy n’affichent aucun score : c’est normal. Strategy n’expose pas public_intelligence ; seuls report.token et report.pdf_url sont disponibles.

---

À lire aussi : Guide d’intégration de l’API | Données structurées et Intelligence Tokens | Intégration Zapier | Intégration Make | Intégration n8n