Webhooks

​

Wann sollten Sie die Veröffentlichung per Webhook wählen?

​

Einen bestehenden Webhook aktualisieren

1. Öffnen Sie die Webhook-Integrationseinstellungen in Sorank.
2. Behalten Sie dieselbe URL und dasselbe Secret bei.
3. Klicken Sie auf Speichern.

{
  "sorank_webhook_version": 2,
  "capabilities": ["article.published", "article.updated"]
}

​

So funktioniert es

​

⚠️ Wichtig: Der Webhook sendet nur die Daten, Sie sind für die Veröffentlichung zuständig

​

Schritt 1: Webhook-Integration öffnen

1. Öffnen Sie im linken Menü Einstellungen und dann Veröffentlichungsplattformen.
2. Scrollen Sie zur Webhook-Karte und klicken Sie auf Connect your website.

​

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.

​

Details der HTTP-Anfrage

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

​

Struktur der Webhook-Nutzlast

​

Version 2: Veröffentlichen, aktualisieren und URL zurückgeben

{
  "sorank_webhook_version": 2,
  "capabilities": ["article.published", "article.updated"]
}

{
  "sorank_webhook_version": 2,
  "status": "published",
  "article_url": "https://example.com/blog/mon-article"
}

​

Neue Versuche und asynchrone Verarbeitung

<meta name="sorank-operation-id" content="IDEMPOTENCY_KEY_FROM_THE_REQUEST" />

​

Eine bestehende Integration migrieren

​

Ereignis: article.published

​

Ereignis: webhook.test

​

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 <meta name="description">-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)

​

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.

​

🚀 Sie sind kein Entwickler? Hosten Sie Ihr Blog lieber auf Sorank

​

Suchen Sie stattdessen eine native Integration?

​

Problem besteht nach der Prüfung weiterhin?