FlowSEO

Webhook für den SEO-Kalender: Beiträge im eigenen System empfangen und die Signatur prüfen

Veröffentlicht am 05. November 2026

Nutzt du kein WordPress, sondern ein eigenes CMS, einen Shop oder eine Automatisierung wie Make oder n8n, schickt der SEO-Kalender freigegebene Beiträge per Webhook direkt an dein System. FlowSEO sendet den fertigen Text als JSON an eine Adresse deiner Wahl und signiert jede Nachricht, damit du prüfen kannst, dass sie von uns kommt. Diese Anleitung richtet sich an die Person, die den Empfang einrichtet.

Webhook anlegen

  1. Öffne den SEO-Kalender und klicke auf Automatisierungen verwalten.
  2. Klicke unter Veröffentlichung auf WordPress oder Webhook verbinden.
  3. Wähle als Art der Verbindung den Webhook.
  4. Gib optional einen Namen ein und trage unter Webhook-Adresse die Adresse deines Empfängers ein. Erlaubt ist nur https, Weiterleitungen folgt FlowSEO nicht.
  5. Optional: Klappe Eigener Header (optional) auf und trage einen Header ein, den FlowSEO bei jeder Nachricht mitschickt, zum Beispiel Authorization mit dem Wert Bearer <dein Token> oder X-Api-Key. Mehr dazu im Abschnitt „Eigener Header“ weiter unten.
  6. Klicke auf Speichern und prüfen.

Danach zeigt FlowSEO einmalig das Webhook-Geheimnis. Kopiere es über Kopieren und hinterlege es in deinem System, es wird nur jetzt angezeigt. Die neue Verbindung steht dann unter Veröffentlichung zur Auswahl. Klicke auf Speichern, damit der Kalender sie nutzt.

Beim Speichern schickt FlowSEO eine Testnachricht vom Typ ping, die in data nur domain.host enthält. Antwortet dein Empfänger nicht mit einem Status 2xx, erscheint „Verbindung gespeichert, die Prüfung ist fehlgeschlagen:“ mit dem Grund.

Im selben Dialog findest du unter So sieht die Nachricht aus die Header, ein vollständiges Beispiel mit deiner Domain, die Prüfung der Signatur in PHP und Node.js und wie FlowSEO deine Antwort auswertet. Das Beispiel entsteht aus demselben Code, mit dem FlowSEO sendet.

Was FlowSEO sendet

Jede Nachricht ist ein POST mit JSON-Inhalt. Zum geplanten Termin kommt ein Ereignis vom Typ content.published. Gekürzt sieht es so aus:

{
  "id": "6f1c2a9e-5b7d-4c3e-9a10-2f8e4d6b1c55",
  "type": "content.published",
  "created_at": "2026-11-12T09:41:00+01:00",
  "data": {
    "domain": { "uuid": "…", "host": "beispiel.de" },
    "publish_at": "2026-11-12T09:41:00+01:00",
    "previous": null,
    "content": {
      "uuid": "…",
      "type": "guide",
      "language": "de",
      "main_keyword": "esstisch für kleine räume",
      "title": "Esstisch für kleine Räume: 7 Ideen",
      "slug": "esstisch-fuer-kleine-raeume",
      "meta_title": "…",
      "meta_description": "…",
      "og_title": "…",
      "og_description": "…",
      "planned_url": "https://beispiel.de/ratgeber/esstisch-fuer-kleine-raeume",
      "version": 3,
      "html": "<p>…</p>",
      "markdown": "…",
      "json_ld": [
        { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "…" }
      ],
      "images": [
        { "role": "hero", "url": "https://…", "alt": "…", "title": "…", "caption": "…", "section_key": null }
      ]
    }
  }
}

Wichtig für die Umsetzung:

  • html und markdown enthalten den Text ohne den Titel. Den Titel nimmst du aus title.
  • images enthält die fertigen Bilder mit Rolle, Alternativtext und Bildunterschrift, das Titelbild zuerst.
  • json_ld ist eine Liste von schema.org-Objekten, die du unverändert als <script type="application/ld+json"> einbinden kannst.
  • previous ist bei einer Aktualisierung gefüllt, mit external_id und url der früheren Veröffentlichung. So überschreibst du einen bestehenden Beitrag, statt einen neuen anzulegen.

Die Signatur prüfen

Jede Nachricht hat drei Header nach dem Standard „Standard Webhooks“:

  • webhook-id: die eindeutige ID der Nachricht, identisch mit id im JSON.
  • webhook-timestamp: der Zeitpunkt des Versands in Sekunden seit 1970.
  • webhook-signature: die Signatur im Format v1,<Base64>.

Die Signatur ist ein HMAC-SHA256 über {webhook-id}.{webhook-timestamp}.{Rohinhalt}. Als Schlüssel dient das Webhook-Geheimnis genau so, wie FlowSEO es angezeigt hat, als Text. Fertige Bibliotheken für Standard Webhooks erwarten dagegen ein Geheimnis mit whsec_ davor und passen deshalb nicht ohne Weiteres; die paar Zeilen unten reichen. In PHP sieht die Prüfung so aus:

$base = $id.'.'.$timestamp.'.'.$rawBody;
$expected = 'v1,'.base64_encode(hash_hmac('sha256', $base, $secret, true));
$valid = hash_equals($expected, $signatureHeader);

In Node.js:

const crypto = require('node:crypto');
const expected = 'v1,' + crypto.createHmac('sha256', secret)
  .update(`${id}.${timestamp}.${rawBody}`)
  .digest('base64');
const valid = signatureHeader.length === expected.length
  && crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));

Nutze immer den unveränderten Rohinhalt der Anfrage, nicht ein neu erzeugtes JSON. Prüfe außerdem, dass der Zeitstempel nicht zu alt ist, etwa höchstens fünf Minuten, und verarbeite jede webhook-id nur einmal: Jede Wiederholung derselben Zustellung trägt dieselbe webhook-id. So entsteht kein doppelter Beitrag, wenn deine Antwort einmal nicht bei FlowSEO ankam.

Eigener Header

Erwartet dein Empfänger ein eigenes Zugangsmerkmal, etwa ein Token, hinterlegst du genau einen Header mit Name und Wert. FlowSEO schickt ihn bei jeder Nachricht mit, auch beim ping.

  • Der Name besteht nur aus Buchstaben, Ziffern und den Zeichen ! # $ % & ' * + - . ^ _ ` | ~, ohne Leerzeichen. Authorization ist erlaubt. Header, die FlowSEO selbst setzt (webhook-id, webhook-timestamp, webhook-signature, Content-Type, Content-Length, Host, User-Agent und die Verbindungs-Header wie Connection oder Transfer-Encoding), lassen sich nicht überschreiben.
  • Der Wert ist eine Zeile ohne Zeilenumbrüche. Er wird verschlüsselt gespeichert und danach nie wieder angezeigt, der Dialog zeigt nur Gesetzt. Lässt du das Feld beim Bearbeiten leer, bleibt der gespeicherte Wert erhalten, solange die Webhook-Adresse gleich bleibt. Änderst du die Adresse, gibst du den Wert neu ein, damit er nie unbemerkt an einen anderen Empfänger geht.
  • Über Header entfernen löschst du ihn wieder, ebenso, wenn du den Namen leerst und speicherst.
  • Der Header gehört nicht zur Signatur. Prüfe ihn also zusätzlich, wenn du ihn als Zugangsschutz nutzt, und verlasse dich für die Herkunft der Nachricht auf die Signatur.

Die veröffentlichte Adresse zurückmelden

Antwortet dein System mit Status 2xx und JSON wie {"url": "https://beispiel.de/ratgeber/esstisch-fuer-kleine-raeume", "id": "4711"}, trägt FlowSEO diese Adresse als veröffentlichte Adresse ein. Statt url darf das Feld auch link heißen. Jede andere erfolgreiche Antwort zählt als zugestellt, nur ohne Adresse. Eine Adresse außerhalb deiner Domain wird nicht übernommen.

Wenn etwas nicht klappt

Beim Speichern einer Verbindung nennt FlowSEO den Grund:

  • „Die Gegenseite hat die Anfrage abgelehnt.“ Dein Empfänger hat mit einem Fehlerstatus geantwortet, oft wegen einer fehlgeschlagenen Signaturprüfung. Prüfe, ob du den Rohinhalt und das richtige Geheimnis verwendest.
  • „Die Adresse leitet weiter. Bitte die endgültige Adresse eintragen.“ Trage die Adresse ein, auf der die Anfrage tatsächlich landet.
  • „Die Adresse ist nicht öffentlich erreichbar oder nicht https.“ Der Empfänger muss über https aus dem Internet erreichbar sein.
  • „Zeitüberschreitung bei der Verbindung.“ FlowSEO wartet höchstens 60 Sekunden. Antworte sofort und verarbeite den Beitrag danach im Hintergrund.

Weiterleitungen (3xx) und Antworten mit 401, 403, 404, 410 oder einem anderen Status 4xx beenden die Zustellung sofort. Bei Zeitüberschreitungen, Verbindungsfehlern, den Status 408 und 429 und Serverfehlern (5xx) versucht FlowSEO die Zustellung noch einmal, insgesamt bis zu dreimal, nach einer und nach fünf Minuten. Scheitert sie endgültig, steht im Kalender „Die Veröffentlichung ist fehlgeschlagen:“ und dahinter der Grund. Wie du neu planst, steht in WordPress-Veröffentlichung klappt nicht.

Geheimnis verloren? Ein neues Geheimnis für eine bestehende Verbindung erzeugt unser Team, das alte gilt dann sofort nicht mehr. Alternativ legst du eine neue Webhook-Verbindung an und wählst sie im Kalender aus.

War dieser Artikel hilfreich?

Zurück zu Content & SEO-Kalender