Guía de integración con Notion

Respuesta rápida: No existe una integración directa entre Surmado y Notion. Conecta ambos con Zapier, Make, n8n o un script propio pequeño. Recibe el webhook report.completed de Surmado y luego llama a la acción “Create database item” de Notion con los campos de report.summary.

Tiempo de lectura: 10 minutos

---

El patrón

1. Trigger: Surmado envía un payload report.completed a un endpoint de webhook (Catch Hook de Zapier, Custom Webhook de Make, Webhook de n8n o tu propio servidor).
2. Lee report.summary para obtener las métricas seleccionadas. En AI Visibility son presence_score, authority_score, competitive_rank, etc. En Site Audit son seo_score, performance_score, accessibility_score, critical_issues_count y el objeto quick_wins. Los informes de Strategy no incluyen resumen: usa solo report.pdf_url y report.token.
3. Crea un elemento en la base de datos de Notion con los valores de las propiedades tomados del payload.
4. (Opcional) Enriquece con una llamada a la API REST GET /v1/reports/{report_id} si necesitas datos más profundos, como public_intelligence.data.platform_variance o public_intelligence.data.audit_data.enrichment.

Configura el webhook pasando webhook_url cuando crees un informe de 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"
  }'

---

Esquemas de base de datos recomendados

Informes de AI Visibility

Propiedad	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	derivado de presence_score abajo

Puedes calcular la propiedad Status con una tabla de búsqueda:

• presence_score < 30 → En riesgo
• 30 <= presence_score < 60 → Necesita mejoras
• presence_score >= 60 → Líder

Informes de Site Audit

Propiedad	Tipo	Campo del payload
Title	Title	report.summary.business_name o 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

Informes de Strategy

Los informes de Strategy solo entregan el token y la URL del PDF por webhook. Un esquema simple:

Propiedad	Tipo	Campo del payload
Title	Title	derivado (marca + fecha)
Token	Text	report.token
Report ID	Text	report.id
Report Date	Date	timestamp
PDF	URL	report.pdf_url

---

Configuración con Zapier (recomendada)

La integración de Zapier con Notion tiene una acción “Create Database Item” que se ajusta bien al payload del webhook.

1. Crea un Zap: Webhooks by Zapier → Catch Hook (copia la URL que te da).
2. Configura un informe de Surmado con webhook_url apuntando a esa URL.
3. Filtro: event = report.completed Y report__product = signal (o scan).
4. Acción: Notion → Create Database Item. Asigna los campos con la salida del webhook (Zapier aplana las claves anidadas con doble guion bajo: report__summary__presence_score).

Guía completa con Zaps de ejemplo: Guía de integración con Zapier.

---

Script propio (sin Zapier)

Si prefieres código, levanta un servidor pequeño que reciba el webhook de Surmado y llame directamente a la API de Notion.

Ejemplo en 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 antes de confiar en el payload. Consulta la Guía de integración de la API para ver el algoritmo HMAC-SHA256.

---

Cómo enriquecer las páginas de Notion con datos más profundos

El resumen del webhook cubre la mayoría de las necesidades. Si quieres desgloses por plataforma (por ejemplo, ChatGPT frente a Claude), llama a la API REST después de crear la página de 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'

Después, actualiza la página de Notion con un bloque de texto enriquecido que contenga los puntajes por plataforma.

---

Solución de problemas

Notion crea la página pero las propiedades están vacías: el tipo de campo en Notion debe coincidir con el del payload. Números como presence_score necesitan una propiedad Number, no Rich Text. Verifica que el tipo de cada propiedad coincida con las tablas de arriba.

El webhook se dispara pero la llamada a Notion falla: Surmado reintenta 3 veces ante respuestas 5xx y luego se rinde. Revisa los registros de tu servidor, corrige el error y vuelve a obtener manualmente por la API REST los informes que se perdieron.

Los informes de Strategy no muestran puntajes: es lo esperado. Strategy no expone public_intelligence; solo están disponibles report.token y report.pdf_url.

---

Relacionado: Guía de integración de la API | Datos estructurados e Intelligence Tokens | Integración con Zapier | Integración con Make | Integración con n8n