> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Doc Sorank - Webhooks ## Wann sollten Sie die Veröffentlichung per Webhook wählen? Der Webhook verbindet Sorank mit einer maßgeschneiderten Website oder einer Automatisierung, die einen Artikel empfangen und veröffentlichen kann. Er eignet sich, wenn Sie dieses Veröffentlichungssystem bereits besitzen oder Ihr Team es einrichten kann. Der Ablauf umfasst drei Schritte: Sorank bereitet den Artikel vor, übermittelt ihn an Ihre Integration, und Ihre Integration veröffentlicht ihn auf Ihrer Website. Sobald dieser Ablauf konfiguriert ist, können Sie Artikel aus Sorank heraus senden oder den Kalender nutzen, um deren Erstellung und Versand zu automatisieren. Mit dem auf dieser Seite beschriebenen Update-Vertrag können Sie außerdem eine neue Version an einen bestehenden Artikel senden. Zum Beispiel wird eine im Editor vorbereitete Änderung an Ihre Website gesendet, wenn Sie auf **Artikel-Update senden** klicken. Wenn Sorank auch das Blog-Hosting übernehmen soll, wählen Sie stattdessen das [gehostete Blog](/de/documentation/host-your-blog-on-sorank). Wenn Ihr CMS einen nativen Connector besitzt, verwenden Sie den in [veröffentlichen und exportieren](/de/documentation/veroeffentlichen-und-exportieren) beschriebenen Ablauf. ## Einen bestehenden Webhook aktualisieren Nach der Aktualisierung Ihres Servers erkennt Sorank die Unterstützung von Updates automatisch bei der nächsten Veröffentlichung oder dem nächsten erneuten Senden, sofern Ihre Integration noch als Legacy erkannt wird. Sorank sendet `webhook.test`; ein Erkennungsfehler verhindert die gewöhnliche Zustellung nicht. Um die Erkennung sofort auszulösen, ohne Ihren Webhook zu trennen: 1. Öffnen Sie die Webhook-Integrationseinstellungen in Sorank. 2. Behalten Sie dieselbe URL und dasselbe Secret bei. 3. Klicken Sie auf **Speichern**. Ihr Server muss auf `webhook.test` mit einem HTTP-Status 2xx und folgendem JSON im Stammverzeichnis antworten: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` Diese Deklaration aktiviert die Aktualisierung veröffentlichter Artikel. `article_url` allein beweist nicht, dass Ihr Server `article.updated` akzeptiert. Die Erkennung ruft fehlende URLs nicht rückwirkend ab: Jede abgeschlossene Veröffentlichung muss ihre eigene `article_url` gemäß dem nachstehenden Vertrag zurückgeben. Sie haben keinen nativen Sorank-Connector für Ihr CMS? Der **Webhook**-Connector ermöglicht es Ihnen, Ihre generierten Artikel an **jede beliebige URL** zu senden, an Zapier, Make, n8n oder einen maßgeschneiderten Endpoint auf Ihrer eigenen entwickelten Website, damit Sie Ihre Inhalte 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 die Veröffentlichung auf Ihrem Blog, Ihrer maßgeschneiderten Website oder einem anderen Tool erstellen, das eingehende HTTP-Anfragen akzeptiert. ## ⚠️ Wichtig: Der Webhook sendet nur die Daten, Sie sind für die Veröffentlichung zuständig Das ist das Wichtigste, was Sie über den Webhook-Connector verstehen müssen. Auf unserer Seite bündelt Sorank **alles, was Sie im JSON benötigen** (Titel, Slug, vollständiger HTML-Inhalt, 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 "Erfolgs"-Status bestätigt nur eine Sache: Die Daten haben Sorank verlassen und Ihr Endpoint hat sie akzeptiert.** Eine einfache historische Empfangsbestätigung bestätigt keine Veröffentlichung. Mit dem nachstehenden Vertrag Version 2 bestätigt eine abgeschlossene Antwort mit `article_url` die Veröffentlichung sofort in Sorank; Ihr Code bleibt für die tatsächliche Veröffentlichung in Ihrem CMS verantwortlich. Mit anderen Worten: Der Webhook ist **ausschließlich ein Zustellmechanismus für Daten**. Den Empfang, die Verarbeitung und die Veröffentlichung in Ihrem CMS liegt vollständig in Ihrer Verantwortung. Wenn der Artikel trotz erfolgreicher Zustellung nicht erscheint, prüfen Sie Empfang, Verarbeitung, Veröffentlichung und die zurückgegebene Antwort. Der Zustellstatus allein erlaubt keine Ursachenidentifikation. ## Schritt 1: Webhook-Integration öffnen 1. Öffnen Sie im linken Menü **Einstellungen** und dann [Veröffentlichungsplattformen](https://app.sorank.com/settings/integrations/publishing). 2. Scrollen Sie zur **Webhook**-Karte und klicken Sie auf **Connect your website**. Webhooks: Schritt 1: Webhook-Integration öffnen ## Schritt 2: Ihren Endpoint konfigurieren 1. Fügen Sie Ihre Ziel-URL in das Feld **Webhook URL** ein (zum Beispiel einen Zapier Catch Hook, einen Make-Webhook oder den Endpoint Ihres eigenen Servers). 2. Fügen Sie bei Bedarf ein **Secret token** hinzu, wenn Ihr Endpoint eine Authentifizierung erfordert. Sorank fügt es als `Bearer`-Token im `Authorization`-Header ein, damit Ihr Server überprüfen kann, dass der Aufruf von Sorank stammt. 3. Klicken Sie auf **Test**, um eine Beispielnutzlast (Ereignistyp `webhook.test`) zu senden und zu bestätigen, dass Ihr Endpoint korrekt antwortet. 4. Klicken Sie auf **Save webhook**, um die Integration zu aktivieren. Webhooks: Schritt 2: Ihren Endpoint konfigurieren ## 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 den Integrationseinstellungen ein Secret konfiguriert haben) Verwenden Sie den `User-Agent`-Header, um Sorank-Traffic in Ihren Protokollen zu identifizieren, und prüfen Sie den `Authorization`-Header auf Ihrer Seite, um sicherzustellen, dass die Anfrage von Sorank und nicht von einem unbekannten Aufrufer stammt. ## Struktur der Webhook-Nutzlast Sorank verwendet drei Ereignisse mit derselben Hülle (`event`, `delivery_id`, `timestamp`, `article`). Eine einzige **POST HTTPS**-Route (zum Beispiel `/sorank-webhook`) genügt: Verarbeiten Sie jeden `event`-Wert auf dieser Route und prüfen Sie das `Authorization`-Token, wenn Sie ein Secret konfiguriert haben. ### Version 2: Veröffentlichen, aktualisieren und URL zurückgeben Um Updates zu aktivieren, muss Ihre Route auf `webhook.test` antworten, ohne Inhalte zu erstellen, mit HTTP 200 und folgendem JSON: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` Für `article.published` erstellen Sie den Artikel und speichern die Zuordnung zwischen **`article.id`** und seiner Kennung in Ihrem CMS. Wenn diese Zuordnung bereits existiert, erstellen Sie kein Duplikat. Für `article.updated` suchen Sie diese Zuordnung und ersetzen den Inhalt des bestehenden Artikels. Wenn der Artikel nicht gefunden wird, geben Sie einen Fehler zurück, zum Beispiel HTTP 404: **Ein Update darf niemals einen neuen Artikel erstellen**. Nach einer tatsächlich abgeschlossenen Veröffentlichung antworten Sie mit HTTP 200 oder 201 und: ```json theme={null} { "sorank_webhook_version": 2, "status": "published", "article_url": "https://example.com/blog/mon-article" } ``` Nach einem abgeschlossenen Update verwenden Sie `"status": "updated"` und die aktuelle öffentliche URL. **Nur `article_url` wird verlangt, nicht die Sitemap-URL.** Geben Sie eine absolute HTTPS-URL auf der mit dem Sorank-Profil verknüpften Website an, nicht die URL Ihrer Automatisierung. Die Antwort muss ein JSON-Objekt unter 16 KiB sein; die URL darf 2.048 Zeichen nicht überschreiten. Geben Sie in `article_url` die **exakte kanonische HTTPS-URL des veröffentlichten Artikels** zurück, entsprechend seinem ``-Tag. Behalten Sie die Schreibweise mit oder ohne `www` und den abschließenden Schrägstrich bei. Lautet die kanonische URL beispielsweise `https://example.com/blog/mein-artikel`, geben Sie sie ohne `www` zurück. Bei `https://www.example.com/blog/mein-artikel/` behalten Sie sowohl `www` als auch den abschließenden Schrägstrich bei. Sorank verwendet diese URL, um die Indexierung in der Google Search Console zu verfolgen. Geben Sie keine alternative URL zurück, nur weil sie zum Artikel weiterleitet oder denselben Inhalt anzeigt. Eine Version-2-Antwort mit `status: published` oder `status: updated` und einer gültigen `article_url` speichert die URL sofort und zeigt **Veröffentlicht** mit dem zugehörigen Link an, auch ohne Backlink-Austausch. Die URL muss zur Website des Profils gehören. Diese abgeschlossenen Antworten warten nicht auf den periodischen Prüfer. Nur `accepted`-Quittungen oder HTTP 202 bleiben zur Überprüfung ausstehend. Backlinks werden separat geprüft: Die Bestätigung der Veröffentlichung beweist nicht das Vorhandensein der Links und validiert keine Gutschriften. Wenn ein Update fehlschlägt, wird die zuletzt geprüfte URL beibehalten. Das Bearbeiten von Text im Editor sendet ihn nicht automatisch: Klicken Sie auf **Update senden**. ### Neue Versuche und asynchrone Verarbeitung Verwenden Sie den `Idempotency-Key`-Header, um dieselbe Operation auf demselben Artikel-Snapshot zu deduplizieren und die gespeicherte Antwort zurückzugeben. `delivery_id` identifiziert nur jeden einzelnen Versuch. Bewahren Sie außerdem die `article.id`-Zuordnung auf, um doppelte Erstellungen zwischen verschiedenen Operationen zu verhindern. Der `X-Sorank-Article-Revision`-Header ermöglicht es, eine ältere Version abzulehnen, die nach einer neueren Version empfangen wurde. Wenn die Verarbeitung nicht abgeschlossen ist, antworten Sie mit HTTP 202 und `"sorank_webhook_version": 2`, `"status": "accepted"` sowie, falls bekannt, `"article_url"`. Ein 202 bestätigt niemals eine Veröffentlichung. Um Sorank zu ermöglichen, diese asynchrone Operation anschließend zu prüfen, fügen Sie **erst nach ihrer tatsächlichen Anwendung** dieses Tag in das öffentliche HTML des Artikels ein: ```html theme={null} ``` Ersetzen Sie den Wert durch den des empfangenen `Idempotency-Key`-Headers. Fügen Sie ihn nicht sofort beim Empfang ein: Die alte Seite beweist nicht das neue Update. Ohne diesen Nachweis bleibt die Prüfung ausstehend und läuft ab. Wenn Ihr Tool dieses Tag nicht veröffentlichen kann, schließen Sie die Veröffentlichung ab, bevor Sie die 200/201-Antwort zurückgeben. ### Eine bestehende Integration migrieren Eine leere oder textuelle 200-Antwort bleibt mit der historischen Zustellung kompatibel, aktiviert jedoch keine Updates. Passen Sie Ihre Route an, klicken Sie auf **Test** und dann auf **Save webhook**: Sorank testet die serverseitigen Fähigkeiten beim Speichern erneut. Eine Änderung der URL oder des Secrets macht laufende alte Prüfungen ungültig. Um bereits veröffentlichte Artikel zu aktualisieren, rekonstruieren Sie deren `article.id`-Zuordnung auf CMS-Seite; Sorank kann diese nicht erraten. ### Ereignis: article.published Wird ausgelöst, wenn Sie einen Artikel aus Sorank heraus veröffentlichen. Das ist das Ereignis, das Ihr Produktions-Endpoint verarbeiten muss, um die Veröffentlichung in Ihrem CMS zu erstellen oder Ihren Automatisierungsfluss auszulösen. ‍ ### Ereignis: webhook.test Wird ausgelöst, wenn Sie in Sorank auf die Schaltfläche Test klicken, um zu prüfen, ob Ihr Endpoint erreichbar ist. Die Nutzlast verwendet fiktive Werte (id enthält nur Nullen, featured\_image wird weggelassen, images ist leer), damit Ihre Integration sie sicher ignorieren oder zur Bestätigung der Konnektivität verwenden kann, ohne eine echte Veröffentlichung zu erstellen. ‍ ### Feldreferenz * **event**, `article.published`, `article.updated` oder `webhook.test`. Verwenden Sie dieses Feld, um die Nutzlast zu routen. * **delivery\_id**, eindeutige UUID zur Nachverfolgung jedes Zustellversuchs. Zur Deduplizierung einer Operation verwenden Sie den `Idempotency-Key`-Header. * **timestamp**, ISO 8601 UTC-Zeitstempel des Zeitpunkts, zu dem das Ereignis ausgelöst wurde. * **article.id**, eindeutige Kennung des Artikels in Sorank. * **article.title**, der H1-Titel des Artikels. * **article.slug**, URL-gerechter Slug in Kleinbuchstaben mit Bindestrichen. * **article.meta\_description**, SEO-Meta-Beschreibung, bereit zur Einfügung in Ihr ``-Tag. * **article.focus\_keyphrase**, primärer Ziel-Keyphrase, der für den Artikel verwendet wird. * **article.content**, vollständiger Artikelinhalt in HTML, einschließlich Überschriften, Absätzen, Listen und eingebetteten Bild-Tags. * **article.featured\_image**, Titelbild-Objekt mit `url`, `alt` und `placement`. Kann bei `article.published` und `article.updated` vorhanden sein. * **article.images**, Array zusätzlicher Bilder im Inhalt. Jeder Eintrag enthält `url`, `alt` und `placement`. Kann leer sein. * **article.word\_count**, Gesamtanzahl der Wörter im Artikelinhalt. * **article.keyword**, identisch mit dem Ziel-Keyphrase, als separates Feld für rückwärtskompatible Integrationen beibehalten. * **article.language**, BCP 47-Sprach-Tag (zum Beispiel `en-US`, `fr-FR`). ## Häufige Anwendungsfälle * **Zapier:** Verwenden Sie einen "Catch Hook"-Trigger, um Artikel an Tausende von Anwendungen wie WordPress, Notion, Airtable oder Google Sheets weiterzuleiten. * **Make:** Verwenden Sie ein Webhooks-Modul, um benutzerdefinierte mehrstufige Veröffentlichungsautomatisierungen zu erstellen. * **n8n:** Verbinden Sie einen Webhook-Knoten mit einem Fluss, der die Veröffentlichung in Ihrem Headless-CMS oder Ihrem Backend erstellt. * **Maßgeschneidertes Backend:** Senden Sie Artikel direkt an Ihre eigene API, um auf einer selbst entwickelten Website, einem Headless-CMS wie Sanity oder Strapi oder einem internen Tool zu veröffentlichen. ## Tipps * Klicken Sie immer auf **Test**, bevor Sie speichern, um zu bestätigen, dass Ihr Endpoint die Anfrage akzeptiert und eine 2xx-Antwort zurückgibt. * Verwenden Sie das `event`-Feld serverseitig, damit `webhook.test`-Aufrufe niemals echte Veröffentlichungen erstellen. * Verwenden Sie `Idempotency-Key`, um eine Operation zu deduplizieren, und `article.id`, um denselben Artikel in Ihrem CMS wiederzufinden. * Halten Sie Ihr **Secret token** privat, prüfen Sie den `Authorization`-Header bei jeder Anfrage und rotieren Sie das Secret regelmäßig. * Verwenden Sie einen HTTPS-Endpoint, um die Artikeldaten während der Übertragung zu sichern. * 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 Daten zustellt, garantiert ein "Erfolg" in Sorank nicht, dass der Artikel auf Ihrer Website online ist. Prüfen Sie jeden Schritt, um die Blockade zu lokalisieren. Hier sind die zu untersuchenden Punkte. ### Ursachen auf der Seite Ihrer Integration * **Ihr CMS-API-Schlüssel ist schreibgeschützt statt lese- und schreibfähig**, das ist eines der häufigsten Probleme. Wenn die Zugangsdaten, die Ihr Code zum Schreiben in Ihr CMS (Sanity, Strapi, Contentful oder ein anderes Headless-Backend) verwendet, nur *Lese-/Ansichtsberechtigungen* haben, empfängt Ihr Endpoint das JSON, schlägt aber lautlos beim Erstellen der Veröffentlichung fehl. Generieren 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**, den Empfang der Nutzlast ist nur die halbe Arbeit. Stellen Sie sicher, dass Ihr Endpoint die Sorank-Felder tatsächlich zuordnet und die Veröffentlichung 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 vorhandenen, kann die Veröffentlichung leer erstellt oder abgelehnt werden. Stellen Sie sicher, dass Sie `article.title`, `article.slug`, `article.content` usw. genau wie oben dokumentiert lesen. * **Ihr Endpoint gibt ein 2xx zurück, löst aber anschließend einen Fehler aus**, wenn Sie die Anfrage quittieren, bevor Sie sie asynchron verarbeiten, ist ein späterer Fehler in Ihrer Veröffentlichungslogik für Sorank nicht sichtbar. Prüfen Sie Ihre eigenen Serverprotokolle, um diese zu erkennen. ### Ursachen auf der Zustellungsseite * **Ihr Webhook-Endpoint antwortet nicht mehr** (Server offline), bringen Sie Ihren Server wieder online und prüfen Sie, ob die URL normal antwortet. * **Die Webhook-URL hat sich geändert, wurde aber in Sorank nicht aktualisiert**, aktualisieren Sie die URL in den Sorank-Integrationseinstellungen. * **Sie haben Ihr Webhook-Secret auf Ihrer Seite neu generiert**, aktualisieren Sie das Secret in Sorank, damit es dem entspricht, was Ihr Server jetzt im `Authorization`-Header erwartet. * **Ihr Endpoint gibt einen Fehler zurück, den Sorank nicht interpretieren kann**, prüfen Sie Ihre Serverprotokolle, um das Problem zu identifizieren, und beheben Sie es auf der Seite Ihres Webhooks. * **Eine Firewall auf Ihrem Server blockiert unsere Anfragen**, fügen Sie die Sorank-IP-Adressen zur Zulassungsliste Ihrer Firewall hinzu oder erlauben Sie den User-Agent `SORANK-Webhook/1.0`. * **Ihr Endpoint benötigt mehr als 30 Sekunden zum Antworten**, optimieren Sie Ihren Endpoint für eine schnellere Antwort oder quittieren 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, nimmt Ihr Planer automatisch den Betrieb auf. Ihr Artikel ist bereits generiert und sicher gespeichert, es geht nichts verloren. ## 🚀 Sie sind kein Entwickler? Hosten Sie Ihr Blog lieber 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-Tool oder einem KI-Tool erstellt haben, wie **Lovable**, **Base44**, **Cursor** oder **Claude Code**, 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 entwickelt, mit der Sie Ihr **Blog automatisch auf Ihrer eigenen Subdomain direkt auf Sorank hosten** können. Kein Code, kein Endpoint zum Pflegen, kein Webhook zum Empfangen. Erfahren Sie hier, wie es funktioniert: [Hosten Sie Ihr Blog auf Sorank](/de/documentation/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. Lesen Sie unsere Anleitungen für [Webflow](/de/documentation/webflow-verbinden), [Shopify](/de/documentation/shopify-verbinden), [WordPress.org](/de/documentation/wordpress-org-verbinden), [WordPress.com](/de/documentation/wordpress-com-verbinden), [Wix](/de/documentation/wix-verbinden) und [HubSpot](/de/documentation/hubspot-mit-sorank-verwenden). ### Problem besteht nach der Prüfung weiterhin? Wenn Sie die oben genannten Punkte geprüft haben und die Veröffentlichung weiterhin fehlschlägt, antworten Sie direkt auf die E-Mail, die Sie erhalten haben: Unser Team wird prüfen, was auf Ihrem Konto vor sich geht. Ihre Artikel bleiben generiert und sicher in Sorank gespeichert. Sobald die Verbindung wiederhergestellt ist, nimmt Ihr Planer automatisch dort wieder auf, wo er aufgehört hat.