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
- Klicken Sie auf Ihr Profilbild in der oberen rechten Ecke und wählen Sie Einstellungen.
- Öffnen Sie den Tab Integrationen.
- Scrollen Sie zur Webhook-Karte und klicken Sie auf Connect your website.
Schritt 2: Konfigurieren Sie Ihren Endpoint
- 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).
- Optional können Sie ein Secret token hinzufügen, falls Ihr Endpoint eine Authentifizierung erfordert. Sorank fügt es als
Bearer-Token in denAuthorization-Header ein, damit Ihr Server überprüfen kann, dass der Aufruf von Sorank stammt. - Klicken Sie auf Test, um eine Beispiel-Nutzlast zu senden (Ereignistyp
webhook.test) und zu bestätigen, dass Ihr Endpoint korrekt antwortet. - 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)
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.
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.
Feldreferenz
- event, Ereignistyp. Entweder
article.publishedoderwebhook.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,altundplacement. Nur beiarticle.published-Ereignissen vorhanden. - article.images, Array zusätzlicher Bilder im Textkörper. Jeder Eintrag hat
url,altundplacement. 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
eventserverseitig aus, damitwebhook.test-Aufrufe niemals echte Beiträge erstellen. - Verwenden Sie
delivery_idals 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.contentusw. 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.