Guia de integração com o Notion

Resposta rápida: não existe uma integração direta entre a Surmado e o Notion. Conecte os dois com Zapier, Make, n8n ou um pequeno script próprio. Receba o webhook report.completed da Surmado e depois chame a ação “Create database item” do Notion com os campos de report.summary.

Tempo de leitura: 10 minutos

---

Padrão

1. Gatilho: a Surmado envia um payload report.completed para um endpoint de webhook (Catch Hook do Zapier, Custom Webhook do Make, Webhook do n8n ou seu próprio servidor).
2. Leia report.summary para as métricas selecionadas. No AI Visibility, são presence_score, authority_score, competitive_rank etc. No Site Audit, são seo_score, performance_score, accessibility_score, critical_issues_count e o objeto quick_wins. Os relatórios de Strategy não incluem resumo: use apenas report.pdf_url e report.token.
3. Crie um item no banco de dados do Notion com os valores das propriedades mapeados a partir do payload.
4. (Opcional) Enriqueça com uma chamada à API REST em GET /v1/reports/{report_id} se precisar de dados mais detalhados, como public_intelligence.data.platform_variance ou public_intelligence.data.audit_data.enrichment.

Configure o caminho do webhook passando webhook_url ao criar um relatório da 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 banco de dados recomendados

Relatórios de AI Visibility

Property	Type	Payload field
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	derived from presence_score below

Uma propriedade Status do tipo select pode ser calculada com uma tabela de consulta:

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

Relatórios de Site Audit

Property	Type	Payload field
Title	Title	report.summary.business_name or 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

Relatórios de Strategy

Os relatórios de Strategy só expõem o token e a URL do PDF pelo webhook. Um esquema enxuto:

Property	Type	Payload field
Title	Title	derived (brand + date)
Token	Text	report.token
Report ID	Text	report.id
Report Date	Date	timestamp
PDF	URL	report.pdf_url

---

Configuração com o Zapier (recomendada)

A integração do Zapier com o Notion tem uma ação “Create Database Item” que se encaixa bem no payload do webhook.

1. Crie um Zap: Webhooks by Zapier → Catch Hook (copie a URL que ele fornece).
2. Configure um relatório da Surmado com webhook_url apontando para essa URL.
3. Filtro: event = report.completed AND report__product = signal (ou scan).
4. Ação: Notion → Create Database Item. Mapeie os campos com a saída do webhook (o Zapier achata as chaves aninhadas com dois sublinhados: report__summary__presence_score).

Passo a passo completo com Zaps de exemplo: Guia de integração com o Zapier.

---

Script próprio (sem Zapier)

Se você prefere código, rode um servidor pequeno que aceite o webhook da Surmado e chame a API do Notion diretamente.

Exemplo em 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);

Verifique a assinatura do webhook antes de confiar no payload – veja o algoritmo HMAC-SHA256 no Guia de integração da API.

---

Enriquecer páginas do Notion com dados mais detalhados

O resumo do webhook atende à maioria das necessidades. Se você quiser detalhamentos por plataforma (por exemplo, ChatGPT e Claude), chame a API REST depois de criar a página no 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'

Depois atualize a página do Notion com um bloco de rich text contendo as pontuações de cada plataforma.

---

Solução de problemas

O Notion cria a página, mas as propriedades ficam vazias – o tipo do campo no Notion precisa corresponder ao do payload. Números como presence_score exigem uma propriedade Number, não Rich Text. Confira se o tipo de cada propriedade corresponde à tabela acima.

O webhook dispara, mas a chamada ao Notion falha – a Surmado tenta de novo 3 vezes em respostas 5xx e depois desiste. Veja os logs do seu servidor, corrija o erro e busque de novo, manualmente, os relatórios perdidos pela API REST.

Os relatórios de Strategy não mostram pontuações – é o esperado. O Strategy não expõe public_intelligence; só report.token e report.pdf_url estão disponíveis.

---

Relacionados: Guia de integração da API | Dados estruturados e Intelligence Tokens | Integração com o Zapier | Integração com o Make | Integração com o n8n