---
title: "Surfer API Webhooks"
description: "Überspringen Sie die Polling-Schleife. Erfahren Sie, wie Sie Webhooks einrichten, damit Surfer Ihren Server benachrichtigt, sobald ein Content Editor bereit ist, ein KI-Artikel fertig generiert wurde oder ein Auto-Optimize-Lauf abgeschlossen ist – ohne wiederholte GET-Anfragen."
url: https://docs.surferseo.com/de/articles/12944183-surfer-api-webhooks
collection: "API"
updated: 2026-10-02
language: de
alternates: [en, fr]
---

# Surfer API Webhooks

Überspringen Sie die Polling-Schleife. Erfahren Sie, wie Sie Webhooks einrichten, damit Surfer Ihren Server benachrichtigt, sobald ein Content Editor bereit ist, ein KI-Artikel fertig generiert wurde oder ein Auto-Optimize-Lauf abgeschlossen ist – ohne wiederholte GET-Anfragen.

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:

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

```

<table data-id="9881abbc-8af1-448a-8105-583969aa1c8b" style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="465961f5-1fe8-4d42-8cf2-2701752e0655"><strong>Feld</strong></p></td><td colspan="1" rowspan="1"><p data-id="7549b62c-7bac-4f8a-82ff-0c4661e7deab"><strong>Typ</strong></p></td><td colspan="1" rowspan="1"><p data-id="674c2cf3-b123-4f65-9f9b-030238071c84"><strong>Beschreibung</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="07c5dc0c-fc34-4cab-90a3-d25344d64343"><code>id</code></p></td><td colspan="1" rowspan="1"><p data-id="95a3e535-d439-4093-9491-3a54c7027348">integer</p></td><td colspan="1" rowspan="1"><p data-id="d30adbbc-8b8e-4cd2-a6c8-88fe7fe5e332">Eindeutige Benachrichtigungs-ID</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="a8200e0a-dd31-477c-a198-b94b1c113dd7"><code>type</code></p></td><td colspan="1" rowspan="1"><p data-id="e8e8ffbd-d91a-4fb3-ab96-93c5b8764411">string</p></td><td colspan="1" rowspan="1"><p data-id="b398f4bc-7e39-4008-8ce5-253cb8033672">Ereignisname (siehe vollständige Liste unten)</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="66dfaf0d-c234-47f0-ba1f-1e214b16fe04"><code>timestamp</code></p></td><td colspan="1" rowspan="1"><p data-id="56cb4305-6504-45b2-9634-6fe21ac3dd67">string</p></td><td colspan="1" rowspan="1"><p data-id="a7402805-b49a-487e-9e09-cfcfef7b4acf">ISO8601 UTC-Zeitstempel des Zeitpunkts, zu dem das Ereignis ausgelöst wurde</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="66bc89d1-3141-4fc2-b98d-11026f011ff2"><code>payload</code></p></td><td colspan="1" rowspan="1"><p data-id="ea929563-1a6d-46cf-8c25-734ff4fa5d0a">object</p></td><td colspan="1" rowspan="1"><p data-id="c405b0dd-6efe-4a4c-8fb4-3bbcc50c8b0a">Ereignisspezifische Daten (variiert je nach Ereignistyp)</p></td></tr></tbody></table>

* * *

## Unterstützte Ereignisse

### Content Editor-Initialisierung

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

<table data-id="53ca7f9f-8380-4906-ac17-c45009a3a956" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="4fe54c63-0e6b-40fc-b02f-170ad9d5aa62"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="63f49255-e9d7-4981-a270-b03e2ce52bb9"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="efcda7e4-4da7-483e-85d9-25f6d274f998"><code>content_editor.initialization.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="cb691419-0fc1-4e9c-9167-13e4d7026460">Content Editor ist einsatzbereit</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="fac22a94-8f37-4465-98d0-835aa600fb41"><code>content_editor.initialization.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="bddeb732-2864-490c-b1a8-bc8b621c172f">Verarbeitung fehlgeschlagen</p></td></tr></tbody></table>

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

```json
{
  "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.

<table data-id="b8a5081c-370b-40b6-a984-7b7ae9ce3baf" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="7864d63a-3983-44b5-be95-50e797a8eda3"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="c781ed7d-c04e-46cb-99b7-55e4252255c1">Wann es ausgelöst wird</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="b0a637f1-893c-4fc2-ac01-083954c9f1e0"><code>content_editor.content_score.recalculated</code></p></td><td colspan="1" rowspan="1"><p data-id="61af32e6-faf9-477c-83d2-8bb0f6c6b633">Bewertung nach einer Inhaltsänderung aktualisiert</p></td></tr></tbody></table>

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

```json
{
  "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.

<table data-id="b928191d-d8e1-4de6-b397-8c1e18c69d4e" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="313d287a-5810-4921-a131-330056540e4e"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="694221ae-d805-49a4-a5e9-22e8c347499f"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="64345988-39b0-46ad-96d7-7a3dfb917d75"><code>content_editor.ai_article.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="1e613be9-5874-4f51-9225-e3b3b89aa36c">Artikel vollständig generiert</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="82366d6b-b678-4b7d-8934-5e56779d0bdd"><code>content_editor.ai_article.waiting_for_user_input</code></p></td><td colspan="1" rowspan="1"><p data-id="533f7c62-2f51-49f9-a6f6-1ce921e43c93">Gliederung ist fertig und wartet auf Überprüfung (nur wenn <code>manual_outline: true</code>)</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="6051faa5-b5bc-404c-ab97-11f7e0454379"><code>content_editor.ai_article.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="47707022-3d8c-42b6-82ca-205a824b008e">Generierung fehlgeschlagen</p></td></tr></tbody></table>

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

* * *

### Auto-Optimize

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

<table data-id="a15dbe3b-a9da-45e1-85ea-8041704268bd" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="bd72eace-0bec-4e9e-a1ac-ddda08a8ee9c"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="811c3cf1-9a21-46e5-b5e2-cd168b26288e"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="735dac58-9794-4d2a-aa2d-2fd4a8961a6e"><code>content_editor.auto_optimize.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="b19beb45-3419-4415-adad-d1a938808d3f">Ausführung abgeschlossen</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="a970e2ce-5cdf-4ae3-adec-14604cb65fd5"><code>content_editor.auto_optimize.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="146c52d6-719e-42ce-9b12-dcc10c1f9cac">Ausführung fehlgeschlagen</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="0f1f5b74-99aa-406a-a1a4-ecf56371aed4"><code>content_editor.auto_optimize.cancelled</code></p></td><td colspan="1" rowspan="1"><p data-id="1e15316b-ed80-4669-ac57-b74f16d524ca">Ausführung wurde abgebrochen</p></td></tr></tbody></table>

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

```json
{
  "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)

<table data-id="e4363959-b594-4fe7-a70e-24f583da9c4b" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="0f7395c8-c0be-4b6d-bb55-38f5b2c0bd0c"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="3a7365bc-cce2-4619-82a1-74997d189982"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="3a5ac58d-bd0f-4aeb-8e4d-0dc2f4e895d5"><code>content_editor.seo_score.calculated</code></p></td><td colspan="1" rowspan="1"><p data-id="d6f538d2-f9d7-4572-8d5c-9a6cdc97e301">SEO-Score wurde berechnet</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="24306719-b021-4b49-b044-29f0fd7600b8"><code>content_editor.seo_score.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="6d574796-3538-45c3-9a36-bf6377d28e43">SEO-Score-Berechnung fehlgeschlagen</p></td></tr></tbody></table>

* * *

### AI Search Score (nur V2)

<table data-id="4299e620-5136-43f4-b7a2-c7734e092ffd" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="d774229a-2b06-4a57-bd81-3502d99299bc"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="a7f48b66-06ec-4210-8077-db8c6080d406"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="f910b483-ec01-493d-aee9-9d2fa4c0bb26"><code>content_editor.ai_search_score.calculated</code></p></td><td colspan="1" rowspan="1"><p data-id="baa8df4c-ec35-45fa-8c42-49fb33ece835"><strong>KI-Suchbewertung berechnet</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="8da51f3e-6a9d-4c7e-9a38-95ea83848388"><code>content_editor.ai_search_score.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="803f4404-462b-4d31-abad-ca4518d928a9">KI-Suchbewertungsberechnung fehlgeschlagen</p></td></tr></tbody></table>

* * *

### Gliederungsgenerierung (nur V2)

<table data-id="578c9b75-c555-411d-a462-d39dd90affe7" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="0ef30008-e1cc-49b4-95a6-49c7684163a3"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="cc77368f-0082-48aa-9c41-158fd214715f"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="2eee763b-e13b-45c4-b2ad-75f8794eaa2e"><code>content_editor.outline.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="10bf6842-f28b-4f77-96cc-845d57673962">Gliederungsgenerierung abgeschlossen</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="5c8e8413-2dbc-41e8-b601-06eda36d9020"><code>content_editor.outline.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="9713ca1c-6d96-4071-a69e-b4e316f55762">Gliederungsgenerierung fehlgeschlagen</p></td></tr></tbody></table>

* * *

### Konkurrenzladen (nur V2)

<table data-id="503bc65b-aaa0-4132-a475-58b7a3c1b3cf" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="e180f47f-708c-4af5-bdb3-d8fa398f15cc"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="e7cbc008-acea-42f9-a1e5-ea2eb0b90fac"><strong>Wann es ausgelöst wird</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="2574ee69-8297-4a87-a5a8-96c887b0713d"><code>content_editor.seo_guidelines.competitors.load_more.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="329c5c91-e80c-4a8f-a5d0-8e2036583499">Zusätzliche Konkurrenten geladen</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="68b5be36-7057-4606-8f2e-9dfd6f64eadc"><code>content_editor.seo_guidelines.competitors.load_more.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="8327d71b-8d8d-4837-bf0b-f96424559a77">Laden zusätzlicher Konkurrenten fehlgeschlagen</p></td></tr></tbody></table>

* * *

## Vollständige Ereignisreferenz

<table data-id="f97116e6-b334-45d8-9ff4-31c9a08b3345" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="85272f09-e7c4-4d57-9368-420d884529ba"><strong>Ereignis</strong></p></td><td colspan="1" rowspan="1"><p data-id="2821feb3-2d8b-4021-a748-36b78edaea25"><strong>Gilt für</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="c1c05819-0884-4bf4-90b2-bc11b0e9d983"><code>content_editor.initialization.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="5260caab-e963-4743-821d-139fee4ef4e6">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="ebd561d1-a99f-4e94-b620-e5a2da4c70c9"><code>content_editor.initialization.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="80fd9401-2fb8-46bd-8db7-d53496f70359">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="3e13bf78-211e-4194-81bc-651a7e1b70fe"><code>content_editor.content_score.recalculated</code></p></td><td colspan="1" rowspan="1"><p data-id="26c3b795-99a6-4a96-a051-bbc87d85fb09">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="c0218b00-6c3c-42dc-984b-a741f4777ad3"><code>content_editor.ai_article.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="0d964181-b1e8-4a7f-9276-1b8243010296">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="5da0fff8-2921-4274-8c1e-6ae75fc4a417"><code>content_editor.ai_article.waiting_for_user_input</code></p></td><td colspan="1" rowspan="1"><p data-id="a9fc8b30-83b9-44d5-881c-c2ee3c7391ea">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="126207b6-dedb-45b7-a6e0-8cb02e668795"><code>content_editor.ai_article.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="a8af3a70-0fac-4dd2-b514-147bf2aabb59">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="38a1a33a-e974-400a-82ce-48d4c578a1a6"><code>content_editor.auto_optimize.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="2458b90e-e525-44b7-98f3-e754cb3d2742">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="2ad60f0d-3a04-4c07-adc6-9310a4276dcb"><code>content_editor.auto_optimize.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="e3ab5bc2-3fcf-4ec1-80b5-3ddf05ad873e">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="d8ad68b2-624e-457f-8021-0e7bef6915c3"><code>content_editor.auto_optimize.cancelled</code></p></td><td colspan="1" rowspan="1"><p data-id="b571974f-7e4e-4fa8-961b-0a1c77b34c1d">V1 + V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="2cdda9dc-a6ac-4916-8364-dfa72d6b7b3c"><code>content_editor.seo_score.calculated</code></p></td><td colspan="1" rowspan="1"><p data-id="3a736e58-58d7-4e86-ad9a-ef92710f53b5">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="d9aae74a-27c2-401a-a75f-ef38515a839e"><code>content_editor.seo_score.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="4602e0dd-9727-43d2-953c-fa5231a53702">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="0f273440-ae5a-40a5-9281-5b537405aafd"><code>content_editor.ai_search_score.calculated</code></p></td><td colspan="1" rowspan="1"><p data-id="81924f81-1500-48ba-b2b4-ed6d373f91d7">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="901799ae-221b-40af-9ae0-dad6e16acb40"><code>content_editor.ai_search_score.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="8f899da7-1fe2-4ba6-a4cd-53625963d27f">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="4a2c7663-e651-4866-8e8d-f55b142c8f21"><code>content_editor.outline.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="101b7acf-832c-45c8-a90c-6fa579dcc935">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="b428f766-8c90-4895-908d-cc6f26b5ac4f"><code>content_editor.outline.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="16feba0e-da5e-4798-8bc6-5bfa1d706844">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="7a626735-f5b6-4151-a669-388558b43de7"><code>content_editor.seo_guidelines.competitors.load_more.completed</code></p></td><td colspan="1" rowspan="1"><p data-id="649c0eb2-54a0-4957-8af7-5acdb65a118c">Nur V2</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="bfe83fff-4126-4dbd-bf95-42e72f3f8be4"><code>content_editor.seo_guidelines.competitors.load_more.failed</code></p></td><td colspan="1" rowspan="1"><p data-id="2f661d38-ed05-4c42-a9df-02ce219187d7">Nur V2</p></td></tr></tbody></table>

* * *

## **Zusätzliche Ressourcen:**

[Surfer API Einführung](https://docs.surferseo.com/en/articles/5700335-surfer-api-introduction.md)

[Surfer API Dokumentation (v1)](https://app.surferseo.com/api/v1/docs#section/Introduction)

[Surfer API Dokumentation (v2)](https://app.surferseo.com/api/v2/docs)

[Surfer API Anwendungsbeispiele](https://docs.surferseo.com/en/articles/8201326-surfer-api-examples-of-use.md)
