Surfer API Webhooks

Webhooks ermöglichen es Surfer, Ihren Server sofort zu benachrichtigen, wenn etwas passiert – z. B. wenn ein Content Editor die Verarbeitung abgeschlossen hat oder ein Auto-Optimize-Lauf beendet ist, sodass Sie nicht ständig auf Updates abfragen müssen.

Webhooks einrichten

Die Webhook-Einrichtung wird vom Support-Team durchgeführt. Gehen Sie wie folgt vor:

1. Richten Sie einen HTTPS-Endpunkt auf Ihrer Seite ein, der POST-Anfragen akzeptiert und mit HTTP 200 OK antwortet.

2. Kontaktieren Sie den Surfer-Support per E-Mail oder Live-Chat und teilen Sie die URL mit.

3. Der Support registriert den Endpunkt und sendet Ihnen einen Verification-Key zur Authentifizierung eingehender Anfragen auf Ihrer Seite.

Nach der Einrichtung sendet Surfer eine POST-Anfrage an Ihren Endpunkt, wenn ein unterstütztes Ereignis ausgelöst wird. Jede Anfrage enthält einen Verification-Key-Header und einen JSON-Body.

Webhook-Payload-Struktur

Alle Webhook-Ereignisse folgen der gleichen Struktur:

{
  "id": 123,
  "type": "event.name.here",
  "timestamp": "2024-06-01T12:00:00Z",
  "payload": {
    ...
  }
}

Unterstützte Ereignisse

Content Editor-Initialisierung

Wird ausgelöst, nachdem POST /api/v2/workspaces/{workspace_id}/content_editors die Verarbeitung abgeschlossen hat.

Payload-Felder: draft_id (integer), permalink_hash (string)

{
  "id": 123,
  "type": "content_editor.initialization.completed",
  "timestamp": "2024-06-01T12:00:00Z",
  "payload": {
    "draft_id": 5632898,
    "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z"
  }
}

Content Score-Neuberechnung

Wird ausgelöst, nachdem Sie den Inhalt in einem Content Editor über die API aktualisiert haben.

Payload-Felder: draft_id (integer), permalink_hash (string), content_score (integer)

{
  "id": 124,
  "type": "content_editor.content_score.recalculated",
  "timestamp": "2024-06-01T12:05:00Z",
  "payload": {
    "draft_id": 5632898,
    "permalink_hash": "kKi7n3pkRk7Gw5cxKDiBAbCAybnDTt2z",
    "content_score": 74
  }
}

KI-Artikelgenerierung

Wird während und nach der Surfer-KI-Artikelgenerierung ausgelöst.

Payload-Felder: draft_id (integer), permalink_hash (string)

Auto-Optimize

Wird ausgelöst, nachdem eine Auto-Optimize-Ausführung abgeschlossen, fehlgeschlagen oder abgebrochen wurde.

Payload-Felder: job_id (integer), draft_id (integer), result (string — nur bei completed)

Das result-Feld ist entweder "optimized" (Inhalt wurde geändert) oder "nothing_to_optimize" (Inhalt war bereits gut optimiert).

{
  "id": 125,
  "type": "content_editor.auto_optimize.completed",
  "timestamp": "2024-06-01T12:10:00Z",
  "payload": {
    "job_id": 456,
    "draft_id": 5632898,
    "result": "optimized"
  }
}

SEO-Score (nur V2)

AI Search Score (nur V2)

Gliederungsgenerierung (nur V2)

Konkurrenzladen (nur V2)

Vollständige Ereignisreferenz

Zusätzliche Ressourcen:

Surfer API Einführung

Surfer API Dokumentation (v1)

Surfer API Dokumentation (v2)

Surfer API Anwendungsbeispiele