> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weelkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook payload

> The envelope and headers your endpoint receives on every delivery.

Every delivery is a `POST` with a JSON body — the **envelope** — and a fixed set of `X-Weelkit-*` headers. The envelope carries the authoritative persisted article version exactly as it was generated; Weelkit never re-renders content at delivery time.

## Envelope

```json theme={null}
{
  "protocolVersion": "weelkit-webhook.v2",
  "eventId": "7b1e9f4a-6c2d-4e8f-9a3b-1c5d7e9f0a2b",
  "operationId": "3f8c2d1e-9a7b-4c6d-8e2f-0b4a6c8d1e3f",
  "eventType": "article.version.created",
  "occurredAtUtc": "2026-08-13T10:15:00Z",
  "organizationId": "d4c3b2a1-...",
  "contract": { "schemaVersion": "article-output.v3", "schemaFingerprint": "weelkit-platform-article.v3+org.abcdef0123456789", "contractVersion": 3, "canonicalCatalogVersion": 3 },
  "article": { "articleId": "...", "articleVersionId": "...", "versionNumber": 3, "title": "...", "contentHtml": "<p>...</p>", "excerpt": "...", "urlSlug": "...", "seoTitle": "...", "metaDescription": "...", "coverImageUrl": null, "categories": ["..."], "tags": ["..."], "ogTitle": null, "ogDescription": null, "ogImageUrl": null, "customFields": { "campaignFocus": "Q3 launch" }, "createdAtUtc": "2026-08-13T10:14:58Z" }
}
```

### Envelope fields

**protocolVersion** `string`

Always `weelkit-webhook.v2` for this protocol version.

**eventId** `string (UUID)`

Identifies the event. Stable across retries of the same delivery.

**operationId** `string (UUID)`

Stable operation identity for the delivery. Retries reuse it — deduplicate by this value. See [Signature verification](https://docs.weelkit.com/integrations/webhook/signature-verification.md#replay-protection).

**eventType** `string`

`article.version.created` for article deliveries, `webhook.test` for connection tests.

**occurredAtUtc** `string (ISO 8601)`

When the event occurred, in UTC.

**organizationId** `string (UUID)`

The organization the article belongs to.

**contract** `object`

Identifies the exact contract the article version was generated against.

**contract properties**

**schemaVersion** `string`

The envelope's article schema version, `article-output.v3`.

**schemaFingerprint** `string`

The effective contract fingerprint starts with `weelkit-platform-article.v3`. Changed canonical field selections add `+sel.<16 hex>`, active custom fields add `+org.<16 hex>`, and changed field properties add `+prop.<16 hex>`. Selection and property suffixes can appear without custom fields. See [Organization article fields](https://docs.weelkit.com/integrations/organization-article-fields.md#effective-contract-fingerprint).

**contractVersion** `number`

Version of the compiled article output contract.

**canonicalCatalogVersion** `number`

Version of the immutable canonical field catalog.

**article** `object | null`

The persisted article version. **`null` for `webhook.test` events** — handle that case before dereferencing.

**article properties**

**articleId** `string`

Stable identifier of the article across versions.

**articleVersionId** `string`

Identifier of this exact persisted version.

**versionNumber** `number`

Monotonically increasing version number within the article.

**title** `string`

Article title.

**contentHtml** `string`

Full article body as a sanitized semantic HTML fragment. It is not a complete HTML document.

**excerpt** `string | null`

Short excerpt.

**urlSlug** `string | null`

URL slug.

**seoTitle** `string | null`

Meta title.

**metaDescription** `string | null`

Meta description.

**coverImageUrl** `string | null`

Cover image URL, when one is set. The envelope carries the URL only, not the cover image's alt text. Images inside `contentHtml` keep their own `alt` attributes.

**categories** `array of string`

Categories. Empty array when none are set.

**tags** `array of string`

Tags. Empty array when none are set.

**ogTitle** `string | null`

Open Graph title, when explicitly enabled and generated.

**ogDescription** `string | null`

Open Graph description, when explicitly enabled and generated.

**ogImageUrl** `string | null`

Open Graph image URL, when explicitly selected or mapped.

**customFields** `object`

Organization custom field values keyed by field key. Empty object when the organization has no active custom fields. See [Organization article fields](https://docs.weelkit.com/integrations/organization-article-fields.md).

**createdAtUtc** `string (ISO 8601)`

When this article version was persisted, in UTC.

### Test event

**Send test** delivers the same envelope and headers with `eventType` set to `webhook.test` and `article` set to `null`:

```json theme={null}
{
  "protocolVersion": "weelkit-webhook.v2",
  "eventId": "7b1e9f4a-6c2d-4e8f-9a3b-1c5d7e9f0a2b",
  "operationId": "3f8c2d1e-9a7b-4c6d-8e2f-0b4a6c8d1e3f",
  "eventType": "webhook.test",
  "occurredAtUtc": "2026-08-13T10:15:00Z",
  "organizationId": "d4c3b2a1-...",
  "contract": { "schemaVersion": "article-output.v3", "schemaFingerprint": "weelkit-platform-article.v3", "contractVersion": 3, "canonicalCatalogVersion": 3 },
  "article": null
}
```

### Fingerprint examples

These examples have no custom fields.

```json fingerprint-examples theme={null}
[
  {
    "id": "untouched",
    "customFieldCount": 0,
    "defaultFieldSelections": {},
    "propertySelections": {},
    "schemaFingerprint": "weelkit-platform-article.v3"
  },
  {
    "id": "selection",
    "customFieldCount": 0,
    "defaultFieldSelections": {
      "excerpt": false
    },
    "propertySelections": {},
    "schemaFingerprint": "weelkit-platform-article.v3+sel.5503e7e99ecb14b5"
  },
  {
    "id": "property",
    "customFieldCount": 0,
    "defaultFieldSelections": {},
    "propertySelections": {
      "coverImage.caption": true
    },
    "schemaFingerprint": "weelkit-platform-article.v3+prop.6ecc058eea423d1f"
  },
  {
    "id": "selection-and-property",
    "customFieldCount": 0,
    "defaultFieldSelections": {
      "excerpt": false
    },
    "propertySelections": {
      "coverImage.caption": true
    },
    "schemaFingerprint": "weelkit-platform-article.v3+sel.5503e7e99ecb14b5+prop.6ecc058eea423d1f"
  }
]
```

## Headers

| Header | Value |
| - | - |
| `X-Weelkit-Signature` | `v1=` followed by hex HMAC-SHA256 over `{timestamp}.{raw body}` |
| `X-Weelkit-Timestamp` | Unix timestamp in seconds used in the signature |
| `X-Weelkit-Event` | The event type, e.g. `article.version.created` |
| `X-Weelkit-Event-Id` | The envelope's `eventId` |
| `X-Weelkit-Operation-Id` | The envelope's `operationId` — stable across retries |
| `X-Weelkit-Protocol-Version` | `weelkit-webhook.v2` |
| `User-Agent` | `Weelkit-Webhooks/2` |
| `Content-Type` | `application/json` |

Verify the signature before parsing the body — see [Signature verification](https://docs.weelkit.com/integrations/webhook/signature-verification.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.