n8n-Integrationsleitfaden

Kurzantwort: Nutzen Sie den Webhook-Trigger-Node von n8n, um report.completed-Ereignisse von Surmado zu empfangen. Richten Sie webhook_url von Surmado auf die n8n-Webhook-URL aus, filtern Sie nach event und report.product und leiten Sie die Payload an Google Sheets, Slack, Postgres oder jede andere Integration weiter. Selbst gehostetes n8n ist kostenlos, n8n Cloud kostet $20/Monat.

Lesezeit: 16 Minuten

Voraussetzungen

n8n-Instanz (selbst gehostet per Docker oder n8n Cloud)
Surmado API-Schlüssel (sur_live_...): Erstellen Sie ihn unter app.surmado.com → Settings → API Keys
Eine öffentliche URL für Ihren n8n-Webhook (n8n Cloud übernimmt das, bei Selbsthosting brauchen Sie eine Domain oder einen Tunnel)

Warum n8n

Selbst hostbar: Ihr Workflow läuft auf Ihrer eigenen Infrastruktur (Docker, Kubernetes, Bare Metal)
Open Source: Sie können jeden Node einsehen und mit eigenem Code erweitern
Keine Abrechnung pro Task: unbegrenzte Ausführungen bei Selbsthosting (nur Serverkosten)
400+ eingebaute Nodes: Notion, Google Sheets, Slack, Airtable, PostgreSQL, HTTP Request, Code usw.
Credentials-Tresor: Speichern Sie Ihren Surmado API-Schlüssel einmal und verwenden Sie ihn in allen Workflows

Schnellstart: Selbst gehostet per Docker

docker volume create n8n_data

docker run -d --name n8n \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  -e N8N_HOST="n8n.yourdomain.com" \
  -e WEBHOOK_URL="https://n8n.yourdomain.com/" \
  n8nio/n8n

Leiten Sie dann n8n.yourdomain.com per Reverse Proxy (Caddy / Nginx / Traefik) auf http://localhost:5678 weiter, damit Surmado Ihren Webhook-Endpunkt über HTTPS erreichen kann.

Surmado API-Schlüssel speichern

Gehen Sie in n8n zu Credentials → New → Header Auth (oder verwenden Sie die eingebaute Credential des generischen HTTP Request-Nodes):

Name: Surmado API
Header name: Authorization
Header value: Bearer sur_live_YOUR_API_KEY

Verweisen Sie von jedem HTTP-Request-Node, der api.surmado.com aufruft, auf diese Credential.

Das Integrationsmuster

Webhook-Trigger-Node. n8n gibt Ihnen eine URL wie https://n8n.yourdomain.com/webhook/abc123.
Surmado konfigurieren, sodass es Berichtsabschlüsse per POST an diese URL sendet, indem Sie beim Erstellen eines Berichts webhook_url übergeben.
IF-Node, um nach event und report.product zu filtern.
(Optional) HTTP Request-Node, der GET /v1/reports/{{ $json.report.id }} für tiefere Daten aufruft.
Ziel-Nodes: Google Sheets, Slack, Notion, Postgres usw.

Beispiel-Payload aus dem Webhook-Node

{
  "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"
    }
  }
}

Strategy-Berichte ("product": "solutions") haben kein summary-Objekt, nur report.token und report.pdf_url.

Workflow 1: AI Visibility zu Google Sheets

Node 1: Webhook-Trigger

HTTP method: POST
Path: surmado-signal (n8n erzeugt daraus https://n8n.yourdomain.com/webhook/surmado-signal)
Response mode: Immediately (200 OK zurückgeben, sobald n8n die Anfrage erhält)

Übergeben Sie diese URL an 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://n8n.yourdomain.com/webhook/surmado-signal"
  }'

Klicken Sie im Webhook-Node auf Listen for test event und lösen Sie dann einen Bericht aus, damit n8n die Struktur der Payload erfasst.

Node 2: IF

Condition 1: {{ $json.event }} equals report.completed Condition 2: {{ $json.report.product }} equals signal

Combine: AND

Node 3: Google Sheets: Append row

Operation: Append Spreadsheet / Sheet: Ihre Tracking-Tabelle

Spalten zuordnen:

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

Aktivieren Sie den Workflow. Jeder abgeschlossene AI Visibility Bericht wird nun erfasst.

Workflow 2: Site Audit mit bedingtem Slack-Alarm

Webhook → IF (report.product = scan) → Google Sheets (immer) → IF (report.summary.performance_score < 70) → Slack.

Slack-Nachricht:

:warning: Performance regression on {{ $json.report.summary.business_name }}

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

View report: {{ $json.report.pdf_url }}

Workflow 3: PDF-Zusammenfassung für Strategy

Strategy enthält keine Zusammenfassung. Ablauf:

Webhook → IF (report.product = solutions) → Send Email (Gmail, SMTP, SendGrid).

E-Mail-Text:

<p>Strategy report <code>{{ $json.report.token }}</code> is ready.</p>
<p><a href="{{ $json.report.pdf_url }}">View the full report (PDF)</a></p>

Tiefere Daten über die REST API abrufen

Die Webhook-Zusammenfassung deckt die meisten Anforderungen ab. Für Plattformvarianz, Probleme pro Seite oder Details zu Inhaltslücken fügen Sie nach dem Filter einen HTTP-Request-Node hinzu:

Node: HTTP Request

Method: GET
URL: https://api.surmado.com/v1/reports/{{ $json.report.id }}
Authentication: predefined credential → Surmado API (die oben erstellte Header Auth)
Response format: JSON

Nachfolgende Nodes können dann {{ $json.public_intelligence.data.platform_variance.chatgpt.presence_score }}, {{ $json.public_intelligence.data.audit_data.enrichment.content_gaps.executive_summary }} usw. verwenden.

Prüfung der Webhook-Signatur

Prüfen Sie im Produktivbetrieb den Header X-Surmado-Signature, bevor Sie der Payload vertrauen. Surmado signiert Webhooks mit HMAC-SHA256 über eine kanonisierte JSON-Darstellung.

Function-Node: Signatur prüfen

const crypto = require('crypto');

const secret = $env.SURMADO_WEBHOOK_SECRET;
const signature = $('Webhook').first().json.headers['x-surmado-signature'];
const body = $('Webhook').first().json.body;

function canonicalize(value) {
  if (value === null || typeof value !== 'object') return JSON.stringify(value);
  if (Array.isArray(value)) return '[' + value.map(canonicalize).join(',') + ']';
  const keys = Object.keys(value).sort();
  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalize(value[k])).join(',') + '}';
}

function asciiEscape(str) {
  return str.replace(/[\u0080-\uffff]/g, c =>
    '\\u' + ('0000' + c.charCodeAt(0).toString(16)).slice(-4)
  );
}

const canonical = asciiEscape(canonicalize(body));
const expected = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(signature, 'hex'))) {
  throw new Error('Invalid webhook signature');
}

return [{ json: body }];

Reihenfolge: Webhook → Function (prüfen) → IF (filtern) → Ziel-Nodes.

Token-Formate

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})

Tokens laufen nicht ab. Signierte Download-URLs der REST API sind etwa 15 Minuten gültig. pdf_url-Magic-Links in Webhooks sind etwa 30 Tage gültig.

Fortgeschrittene Muster

Nach Produkt mit Switch verzweigen

Verwenden Sie einen Switch-Node auf $json.report.product mit Fällen für signal, scan, solutions. Jeder Fall führt zu einem produktspezifischen Workflow. Eine einzige Webhook-URL deckt jeden Berichtstyp ab.

In Postgres für Zeitreihenanalysen speichern

Fügen Sie nach dem IF-Filter einen Postgres-Node hinzu, der (timestamp, token, report_id, product, business_name, presence_score, authority_score, ...) per INSERT in eine Berichtstabelle schreibt. Fragen Sie sie später mit Grafana oder Metabase für Trendansichten ab.

Routing für mehrere Agenturkunden

Verwenden Sie einen Data store (oder eine externe Datenbank), der business_name / brand_slug der Konfiguration des jeweiligen Kunden zuordnet (welcher Slack-Kanal, welcher Tabellenreiter usw.). Schlagen Sie ihn pro Bericht nach und leiten Sie dynamisch weiter.

Fehlerbehebung

Der Webhook wird nicht ausgelöst: Aktivieren Sie den Workflow (n8n verarbeitet Webhooks nur, wenn er aktiv ist, nicht während des Testens). Prüfen Sie, dass webhook_url beim Erstellen des Berichts gesetzt wurde. Testen Sie webhook.site als Zwischen-URL, um zu prüfen, dass Surmado die erwartete Payload sendet.

Der HTTP-Request-Node liefert 401: Die Credential ist nicht angehängt oder dem Schlüssel fehlt das Präfix Bearer . Der vollständige Header-Wert muss Bearer sur_live_... lauten.

Felder sind in nachfolgenden Nodes leer: Prüfen Sie den Produkttyp. Strategy-Webhooks enthalten kein report.summary, nur report.token und report.pdf_url sind befüllt.

Selbst gehosteter Webhook nicht erreichbar: Surmado verlangt HTTPS. Läuft n8n auf localhost, verwenden Sie einen Tunnel (ngrok, Cloudflare Tunnel) oder betreiben Sie es hinter einem Reverse Proxy mit gültigem TLS-Zertifikat.

Die Signaturprüfung schlägt bei Nicht-ASCII-Zeichen fehl: Die obige Hilfsfunktion canonicalize behandelt das. Haben Sie eine eigene geschrieben, müssen Sie Nicht-ASCII-Zeichen per ASCII-Escape maskieren, damit das Ergebnis der Ausgabe von json.dumps(..., ensure_ascii=True) in Python entspricht, die Surmado verwendet.

Verwandt: API-Integrationsleitfaden | Strukturierte Daten und Intelligence Tokens | Zapier-Integration | Make-Integration | Notion-Integration