Webhook Callback Contract

This document only describes what callback users receive on their webhook URL.

Before callbacks: set up webhook endpoint

Complete this setup first. Callback delivery requires an enabled webhook URL and a valid signing secret.

Open Workspace -> Settings -> Webhooks.
Set your Callback URL (HTTPS required). This is the URL that receives all webhook events.
Enable webhooks and save settings.
Copy your signing secret (`whsec_...`) and store it securely. You need this secret to verify `X-ContentKit-Signature`.
Send a test event and confirm your endpoint returns a `2xx` response.

If callback URL is missing, webhook is disabled, or your endpoint returns non-2xx, delivery is treated as failed.

Callback request format

Method

POST

Common callback headers

Content-Type: application/json
X-ContentKit-Signature: t=<timestamp>,v1=<hmac_sha256>
X-ContentKit-Timestamp: <timestamp>

1) Publish callback (`event: content.generated`)

Payload sent to callback user:

json

{
  "id": "evt_0f1d2c3b4a5e6f70",
  "event": "content.generated",
  "created": 1739865600,
  "data": {
    "job_id": "job_1739865600",
    "workspace_id": "workspace-id-or-unknown",
    "domain": "keyword-or-title",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "id": "generated-article-id",
      "keyword": "best ai seo tools",
      "title": "Best AI SEO Tools in 2026",
      "slug": "best-ai-seo-tools-in-2026",
      "content": "<h1>...</h1>",
      "meta_description": "...",
      "json_ld": {}
    }
  }
}

`data.result` is the raw generated article object.

Callback user should return `2xx` JSON:

json

{
  "id": "external-post-id-123",
  "link": "https://client.example.com/blog/my-published-post"
}

`url` is accepted instead of `link`.

2) Fix apply callback (`event: fix.apply`)

When fix apply uses `integration_type=webhook`, payload includes:

json

{
  "id": "evt_214a2f9bdc294df1",
  "event": "fix.apply",
  "created": 1739866600,
  "data": {
    "target_url": "https://client.example.com/blog/my-post",
    "summary": {
      "total": 3,
      "processed": 3,
      "failed": 0
    },
    "fixes": [
      {
        "type": "meta",
        "location": "<head>",
        "action": "replace",
        "suggested_value": "<title>Updated Title</title>"
      },
      {
        "type": "schema",
        "location": "<head>",
        "action": "after",
        "suggested_value": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\"}"
      },
      {
        "type": "image_alt",
        "location": "https://cdn.example.com/image.jpg",
        "action": "replace",
        "suggested_value": "Descriptive alt text"
      }
    ]
  }
}

Callback user should return `2xx` JSON:

json

{
  "id": "external-fix-op-456",
  "link": "https://client.example.com/blog/my-post"
}

`url` is accepted instead of `link`.

3) Exact fix shapes by source

This section defines the exact `data.fixes` shape depending on source endpoint.

A) If source is `/apply-fix` (manual fixes)

`data.fixes` is passed through exactly as sent by the client.

Supported `type` values:

meta
schema
content_addition
content_replacement
structural
image_alt
faq

Typical fields per fix:

required: `type`, `location`, `suggested_value`
optional: `action` (`before|after|replace`, default `after`)
optional: `current_value`, `reasoning`, `location_heading`

B) If source is `/apply-seo` (generated fixes)

`data.fixes` is generated in this exact mapping:

Meta title -> `type: "meta"`, `action: "replace"`, `suggested_value: "<title>...</title>"`
Meta description -> `type: "meta"`, `action: "replace"`, `suggested_value: "<meta name=\"description\" content=\"...\">"`
Schema item -> `type: "schema"`, `action: "after"`, `suggested_value: "<json string>"`
Alt text item -> `type: "image_alt"`, `action: "replace"`, `location: <image_url>`, `suggested_value: <alt_text>`
FAQ block -> two fixes are generated: (1) `type: "content_addition"`, `action: "after"`, `suggested_value: "<div class=\"faq-section\">...</div>"`; (2) `type: "schema"`, `action: "after"`, `suggested_value: "<FAQPage json string>"`

Important: FAQ from `/apply-seo` is not sent as `type: "faq"`; it is sent as `content_addition` plus `schema`.

4) Fix completion status callback (`event: fix.generated`)

After fix job completes, status callback may be sent:

json

{
  "id": "evt_65e5d1e6c83d4040",
  "event": "fix.generated",
  "created": 1739866000,
  "data": {
    "job_id": "7c937cd0-a110-4f08-9a10-fdb03f1caef3",
    "workspace_id": "workspace-id",
    "domain": "https://example.com/page-being-fixed",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "status": "success",
      "id": "cms-resource-id"
    }
  }
}

Delivery failure rule

If callback user returns non-2xx, that delivery is treated as failed.