Surfer API Webhooks

Webhooks let Surfer notify your server the moment something happens; like a Content Editor finishing processing or an Auto-Optimize run completing, so you don't have to poll for updates.

Setting up webhooks

Webhook setup is handled by the Support Team. To get started:

1. Set up an HTTPS endpoint on your end that accepts POST requests and responds with HTTP 200 OK.

2. Contact Surfer Support via email or live chat and share the URL.

3. Support will register the endpoint and send you a Verification-Key to use for authenticating incoming requests on your end.

Once set up, Surfer will send a POST request to your endpoint whenever a supported event fires. Each request includes a Verification-Key header and a JSON body.

Webhook payload structure

All webhook events follow the same envelope:

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

Supported events

Content Editor initialization

Fires after POST /api/v2/workspaces/{workspace_id}/content_editors completes processing.

Payload fields: 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 recalculation

Fires after you update the content inside a Content Editor via the API.

Payload fields: 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
  }
}

AI Article generation

Fires during and after Surfer AI article generation.

Payload fields: draft_id (integer), permalink_hash (string)

Auto-Optimize

Fires after an Auto-Optimize run completes, fails, or is cancelled.

Payload fields: job_id (integer), draft_id (integer), result (string — only on completed)

The result field is either "optimized" (content was changed) or "nothing_to_optimize" (content was already well-optimized).

{
  "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 (V2 only)

AI Search score (V2 only)

Outline generation (V2 only)

Competitor loading (V2 only)

Full event reference

Additional resources:

Surfer API Introduction

Surfer API Documentation (v1)

Surfer API Documentation (v2)

Surfer API Examples of Use