Webhooks

Keine native Sorank-Integration für Ihr CMS verfügbar? Mit dem Webhook-Connector können Sie Ihre generierten Artikel an jede beliebige URL senden, an Zapier, Make, n8n oder einen benutzerdefinierten Endpoint auf Ihrer eigenen, selbst programmierten Website, sodass Sie Ihre Inhalte überall dort veröffentlichen können, wo Sie sie benötigen.

So funktioniert es

Wenn Sie einen Artikel in Sorank veröffentlichen, senden wir eine POST-Anfrage mit einer strukturierten JSON-Nutzlast an die von Ihnen konfigurierte URL. Ihr Endpoint oder Ihr Automatisierungstool kann die Nutzlast dann verarbeiten und den Beitrag in Ihrem Blog, Ihrer benutzerdefinierten Website oder jedem anderen Tool erstellen, das eingehende HTTP-Anfragen akzeptiert.

⚠️ Wichtig: Der Webhook sendet nur die Daten, veröffentlichen müssen Sie sie selbst

Das ist das Wichtigste, was Sie über den Webhook-Connector verstehen müssen. Auf unserer Seite verpackt Sorank alles, was Sie benötigen, in das JSON (Titel, Slug, vollständiger HTML-Textkörper, Meta-Beschreibung, Bilder, Sprache und mehr) und sendet es an Ihre URL. Sobald dieses JSON erfolgreich gesendet wurde, markiert Sorank die Zustellung als erfolgreich.

Dieser Status "erfolgreich" bestätigt nur eines: Die Daten haben Sorank verlassen und Ihr Endpoint hat sie angenommen. Wir haben keine Möglichkeit zu wissen, was danach auf Ihrer Seite geschieht. Wir können nicht erkennen, ob Ihr Code das JSON tatsächlich gelesen, die Felder korrekt zugeordnet oder den Artikel auf Ihrer Website live geschaltet hat.

Mit anderen Worten: Der Webhook ist lediglich ein Zustellmechanismus für die Daten. Das Empfangen, Auswerten und Veröffentlichen in Ihrem CMS liegt vollständig in Ihrer Verantwortung. Wenn der Artikel nicht in Ihrem Blog erscheint, obwohl Sorank "erfolgreich" anzeigt, liegt das Problem fast immer darin, wie Ihre Integration die Nutzlast empfängt und verarbeitet, und nicht an der Zustellung selbst.

Schritt 1: Öffnen Sie die Webhook-Integration

1. Klicken Sie auf Ihr Profilbild in der oberen rechten Ecke und wählen Sie Einstellungen.
2. Öffnen Sie den Tab Integrationen.
3. Scrollen Sie zur Webhook-Karte und klicken Sie auf Connect your website.

Schritt 2: Konfigurieren Sie Ihren Endpoint

1. Fügen Sie Ihre Ziel-URL in das Feld Webhook URL ein (zum Beispiel einen Zapier-Catch-Hook, einen Make-Webhook oder Ihren eigenen Server-Endpoint).
2. Optional können Sie ein Secret token hinzufügen, falls Ihr Endpoint eine Authentifizierung erfordert. Sorank fügt es als Bearer-Token in den Authorization-Header ein, damit Ihr Server überprüfen kann, dass der Aufruf von Sorank stammt.
3. Klicken Sie auf Test, um eine Beispiel-Nutzlast zu senden (Ereignistyp webhook.test) und zu bestätigen, dass Ihr Endpoint korrekt antwortet.
4. Klicken Sie auf Save webhook, um die Integration zu aktivieren.

Details der HTTP-Anfrage

Jeder Webhook, den Sorank an Ihren Endpoint sendet, folgt demselben HTTP-Vertrag. Folgendes wird Ihr Server empfangen:

• Method: POST
• Content-Type: application/json
• User-Agent: SORANK-Webhook/1.0
• Authorization: Bearer {webhook_secret} (optional, wird nur gesendet, wenn Sie in Ihren Integrationseinstellungen ein Secret konfiguriert haben)

Verwenden Sie den User-Agent-Header, um Sorank-Traffic in Ihren Protokollen zu identifizieren, und überprüfen Sie den Authorization-Header auf Ihrer Seite, um sicherzustellen, dass die Anfrage von Sorank stammt und nicht von einem unbekannten Aufrufer.

Struktur der Webhook-Nutzlast

Sorank sendet zwei Arten von Webhook-Ereignissen. Beide verwenden denselben übergeordneten Umschlag (event, delivery_id, timestamp, article), sodass Ihre Integration nur anhand des Feldes event entscheiden muss, wie die Nutzlast weitergeleitet wird.

Ereignis: article.published

Wird jedes Mal ausgelöst, wenn Sie einen Artikel aus Sorank veröffentlichen. Dies ist das Ereignis, das Ihr Produktions-Endpoint verarbeiten sollte, um den Beitrag in Ihrem CMS zu erstellen oder Ihren Automatisierungsablauf auszulösen.

{
  "event": "article.published",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Best SEO Practices for 2025",
    "slug": "best-seo-practices-2025",
    "meta_description": "Discover the best SEO practices for 2025.",
    "focus_keyphrase": "seo practices",
    "content": "<h1>Best SEO Practices</h1><p>Article body content here...</p>",
    "featured_image": {
      "url": "https://storage.example.com/image.jpg",
      "alt": "Best SEO Practices for 2025",
      "placement": "hero"
    },
    "images": [
      {
        "url": "https://storage.example.com/image2.jpg",
        "alt": "SEO diagram",
        "placement": "body"
      }
    ],
    "word_count": 1500,
    "keyword": "seo practices",
    "language": "en-US"
  }
}

Ereignis: webhook.test

Wird ausgelöst, wenn Sie in Sorank auf die Schaltfläche Test klicken, um zu überprüfen, ob Ihr Endpoint erreichbar ist. Die Nutzlast verwendet Platzhalterwerte (id besteht nur aus Nullen, featured_image wird weggelassen, images ist leer), sodass Ihre Integration sie gefahrlos ignorieren oder zur Bestätigung der Verbindung nutzen kann, ohne einen echten Beitrag zu erstellen.

{
  "event": "webhook.test",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "00000000-0000-0000-0000-000000000000",
    "title": "Test Article - Webhook Connectivity Check",
    "slug": "test-article-webhook-check",
    "meta_description": "This is a test payload to verify webhook connectivity.",
    "focus_keyphrase": "webhook test",
    "content": "<h2>Test Article</h2><p>This is a test payload sent by SORANK to verify your webhook endpoint is working correctly.</p>",
    "images": [],
    "word_count": 20,
    "keyword": "webhook test",
    "language": "en-US"
  }
}

Feldreferenz

• event, Ereignistyp. Entweder article.published oder webhook.test. Anhand dieses Feldes wird die Nutzlast weitergeleitet.
• delivery_id, Eindeutige UUID für jeden Zustellversuch. Speichern Sie sie auf Ihrer Seite, um wiederholte Versuche zu deduplizieren und doppelte Veröffentlichungen zu vermeiden.
• timestamp, ISO-8601-UTC-Zeitstempel des Zeitpunkts, zu dem das Ereignis ausgelöst wurde.
• article.id, Eindeutige Kennung des Artikels in Sorank.
• article.title, Die H1 / der Titel des Artikels.
• article.slug, URL-freundlicher Slug, in Kleinbuchstaben und mit Bindestrichen.
• article.meta_description, SEO-Meta-Beschreibung, bereit zum Einfügen in Ihren <meta name="description">-Tag.
• article.focus_keyphrase, Primäre Ziel-Keyphrase, die für den Artikel verwendet wurde.
• article.content, Vollständiger Artikeltext in HTML, einschließlich Überschriften, Absätzen, Listen und Inline-Bild-Tags.
• article.featured_image, Titelbild-Objekt mit url, alt und placement. Nur bei article.published-Ereignissen vorhanden.
• article.images, Array zusätzlicher Bilder im Textkörper. Jeder Eintrag hat url, alt und placement. Kann leer sein.
• article.word_count, Gesamtanzahl der Wörter im Artikeltext.
• article.keyword, Identisch mit der Focus-Keyphrase, als separates Feld für abwärtskompatible Integrationen beibehalten.
• article.language, BCP-47-Sprach-Tag (z. B. en-US, fr-FR).

Häufige Anwendungsfälle

• Zapier: Verwenden Sie einen "Catch Hook"-Trigger, um Artikel an Tausende von Apps wie WordPress, Notion, Airtable oder Google Sheets weiterzuleiten.
• Make: Verwenden Sie ein Webhooks-Modul, um benutzerdefinierte, mehrstufige Veröffentlichungs-Automatisierungen zu erstellen.
• n8n: Binden Sie einen Webhook-Node in einen Ablauf ein, der den Beitrag in Ihrem Headless-CMS oder Backoffice erstellt.
• Eigenes Backend: Senden Sie Artikel direkt an Ihre eigene API, um sie auf einer handcodierten Website, einem Headless-CMS wie Sanity oder Strapi oder einem beliebigen internen Tool zu veröffentlichen.

Tipps

• Klicken Sie immer auf Test, bevor Sie speichern, um zu bestätigen, dass Ihr Endpoint die Anfrage annimmt und eine 2xx-Antwort zurückgibt.
• Werten Sie das Feld event serverseitig aus, damit webhook.test-Aufrufe niemals echte Beiträge erstellen.
• Verwenden Sie delivery_id als Idempotenzschlüssel, um zu vermeiden, dass derselbe Artikel bei wiederholten Versuchen zweimal veröffentlicht wird.
• Halten Sie Ihr Secret token geheim, überprüfen Sie den Authorization-Header bei jeder Anfrage und wechseln Sie das Secret regelmäßig.
• Verwenden Sie einen HTTPS-Endpoint, um die Artikeldaten während der Übertragung sicher zu halten.
• Sobald die Verbindung hergestellt ist, wird jeder in Sorank veröffentlichte Artikel automatisch an Ihre Webhook-URL gesendet.

🔄 Warum Ihre Artikel möglicherweise nicht erscheinen (Fehlerursachen)

Da der Webhook nur die Daten zustellt, garantiert ein "erfolgreich" in Sorank nicht, dass der Artikel auf Ihrer Website live ist. Wenn etwas schiefgeht, liegt es fast immer auf der Empfängerseite. Hier sind die häufigsten Ursachen und wie Sie sie beheben.

Ursachen auf Ihrer Integrationsseite

• Ihr CMS-API-Schlüssel ist schreibgeschützt statt mit Lese- & Schreibrechten ausgestattet, Dies ist eines der häufigsten Probleme. Wenn die Zugangsdaten, die Ihr Code zum Schreiben in Ihr CMS (Sanity, Strapi, Contentful oder ein beliebiges Headless-Backend) verwendet, nur über Ansichts- / Leserechte verfügen, empfängt Ihr Endpoint zwar das JSON, scheitert aber stillschweigend beim Erstellen des Beitrags. Erstellen Sie einen Schlüssel mit Schreibzugriff und aktualisieren Sie ihn in Ihrer Integration.
• Ihr Code empfängt das JSON, sendet es aber nie an Ihr CMS, Das Empfangen der Nutzlast ist nur die halbe Arbeit. Stellen Sie sicher, dass Ihr Endpoint die Sorank-Felder tatsächlich zuordnet und den Beitrag in Ihrem CMS oder Ihrer Datenbank erstellt. Protokollieren Sie die eingehende Nutzlast und bestätigen Sie, dass Ihr Veröffentlichungsaufruf ausgeführt wird und erfolgreich ist.
• Die Feldzuordnung ist falsch, Wenn Ihr Code andere Feldnamen erwartet als die in der Nutzlast, wird der Beitrag möglicherweise leer erstellt oder abgelehnt. Überprüfen Sie genau, dass Sie article.title, article.slug, article.content usw. exakt so auslesen, wie oben dokumentiert.
• Ihr Endpoint gibt 2xx zurück, wirft aber danach einen Fehler, Wenn Sie die Anfrage bestätigen, bevor Sie sie asynchron verarbeiten, ist ein späterer Fehler in Ihrer Veröffentlichungslogik für Sorank nicht sichtbar. Überprüfen Sie Ihre eigenen Server-Protokolle, um diese zu erkennen.

Ursachen auf der Zustellungsseite

• Ihr Webhook-Endpoint antwortet nicht mehr (Server offline), Bringen Sie Ihren Server wieder online und überprüfen Sie, ob die URL normal antwortet.
• Die Webhook-URL hat sich geändert, wurde aber nicht in Sorank aktualisiert, Aktualisieren Sie die URL in Ihren Sorank-Integrationseinstellungen.
• Sie haben Ihr Webhook-Secret auf Ihrer Seite neu generiert, Aktualisieren Sie das Secret in Sorank, damit es mit dem übereinstimmt, das Ihr Server nun im Authorization-Header erwartet.
• Ihr Endpoint gibt einen Fehler zurück, den Sorank nicht interpretieren kann, Überprüfen Sie Ihre Server-Protokolle, um das Problem zu identifizieren, und beheben Sie es dann auf Ihrer Webhook-Seite.
• Eine Firewall auf Ihrem Server blockiert unsere Anfragen, Setzen Sie die Sorank-IPs in Ihrer Firewall auf die Whitelist oder erlauben Sie den SORANK-Webhook/1.0-User-Agent.
• Ihr Endpoint benötigt mehr als 30 Sekunden zum Antworten, Optimieren Sie Ihren Endpoint, damit er schneller antwortet, oder bestätigen Sie die Anfrage sofort und verarbeiten Sie sie asynchron.

Wenn Sorank einen Artikel nicht an Ihren Endpoint zustellen kann, wird Ihr Planer automatisch pausiert und Sie erhalten eine E-Mail. Sobald Sie das Problem beheben und Ihren Webhook in Sorank erneut verbinden, wird Ihr Planer von selbst fortgesetzt. Ihr Artikel ist bereits generiert und sicher gespeichert, es geht nichts verloren.

🚀 Kein Entwickler? Hosten Sie Ihren Blog stattdessen auf Sorank

Der Webhook erfordert, dass Sie Code schreiben und pflegen, der das JSON empfängt und auf Ihrer Website veröffentlicht. Wenn Sie Ihre Website mit einem No-Code- oder KI-Tool wie Lovable, Base44, Cursor oder Claude Code erstellt haben und nicht in der Lage sind, einen Endpoint zu entwickeln und zu hosten, der den Webhook empfängt und den Artikel veröffentlicht, gibt es einen viel einfacheren Weg.

Wir haben eine Lösung geschaffen, mit der Sie Ihren Blog automatisch auf Ihrer eigenen Subdomain hosten können, direkt auf Sorank. Kein Code, kein zu pflegender Endpoint, kein zu empfangender Webhook. Erfahren Sie hier, wie es funktioniert: Host your blog on Sorank.

Suchen Sie stattdessen eine native Integration?

Wenn Ihre Plattform unterstützt wird, ist ein direkter Connector einfacher als der Webhook. Sehen Sie sich unsere Anleitungen für Webflow, Shopify, WordPress.org, WordPress.com, Wix und HubSpot an.

Das Problem besteht nach der Überprüfung weiterhin?

Wenn Sie die oben genannten Punkte überprüft haben und die Veröffentlichung weiterhin fehlschlägt, antworten Sie direkt auf die E-Mail, die Sie erhalten haben: Unser Team wird untersuchen, was in Ihrem Konto geschieht.

Ihre Artikel bleiben in Sorank generiert und sicher gespeichert. Sobald die Verbindung wiederhergestellt ist, setzt Ihr Planer automatisch dort fort, wo er aufgehört hat.