Webhook payloads & data

Payload structure

All webhook payloads follow a consistent structure with two main sections:

{
  "data": {
    // Content-specific data about the changed item
  },
  "webhook": {
    "event": "event.type",
    "target": "https://your-webhook-endpoint.com"
  }
}

Webhook metadata

The webhook object is included in all webhook payloads and contains:

Field	Type	Description
`event`	string	The event type that triggered this webhook (e.g., `page.published`)
`target`	string (URI)	The webhook endpoint URL that received this notification

Page webhook payloads

Data fields

Field	Type	Description	Required
`id`	string	Page slug	Yes
`buttercms_id`	integer	Page numeric ID	Yes
`page_type`	string	Page type key, or `*` for single pages	Yes
`editor`	string	Full name of the editor who made the change	Yes
`name`	string	Human-readable page name	Yes
`timestamp`	string	Timestamp when webhook was generated	Yes
`locale`	string	Code of the locale a change applies to. Present for locale-scoped changes in localized organizations; absent otherwise	No
`status`	string	Current page status: `draft`, `published`, `scheduled`, or `deleted`	Yes
`updated`	string (datetime)	Last updated timestamp in ISO 8601 format	Yes
`published`	string/null (datetime)	Published timestamp, null if not published	No
`scheduled`	string/null (datetime)	Scheduled publication timestamp, null if not scheduled	No

Example: Page published

{
  "data": {
    "id": "product-launch",
    "buttercms_id": 5678,
    "page_type": "landing",
    "editor": "Marketing Team",
    "name": "Product Launch Landing Page",
    "timestamp": "2024-01-15T14:30:00",
    "status": "published",
    "updated": "2024-01-15T14:30:00.123456Z",
    "published": "2024-01-15T14:30:00.123456Z",
    "scheduled": null
  },
  "webhook": {
    "event": "page.published",
    "target": "https://yourapp.com/webhooks/buttercms"
  }
}

Example: Page deleted

{
  "data": {
    "id": "old-promotion",
    "buttercms_id": 3456,
    "page_type": "promo",
    "editor": "Content Manager",
    "name": "Old Promotion Page",
    "timestamp": "2024-01-15T20:15:00",
    "status": "deleted",
    "updated": "2024-01-15T20:15:00.111222Z",
    "published": "2024-01-10T10:00:00.000000Z",
    "scheduled": null
  },
  "webhook": {
    "event": "page.delete",
    "target": "https://yourapp.com/webhooks/buttercms"
  }
}

Blog Post webhook payloads

Data fields

Field	Type	Description	Required
`id`	string	Blog post slug	Yes
`_id`	integer	Blog post numeric ID	Yes
`locale`	string	Locale code — present only in `post.localization.*` event payloads	No

The post.localization.* events (post.localization.published, post.localization.draft, post.localization.delete) add a locale field identifying which locale changed, e.g. "locale": "es". The default-locale post.* events omit this field.

Example: Blog Post published

{
  "data": {
    "id": "announcing-new-features",
    "_id": 5678
  },
  "webhook": {
    "event": "post.published",
    "target": "https://yourapp.com/webhooks/buttercms"
  }
}

Blog post webhook payloads are intentionally lightweight, containing only the post slug and ID. To get the full post content, use the slug to fetch the complete post data from the ButterCMS API.

Fetching full post data

// After receiving the webhook
const { data, webhook } = webhookPayload;

if (webhook.event === 'post.published') {
  // Fetch the full post using the slug
  const butter = require('buttercms')('your-api-token');
  const response = await butter.post.retrieve(data.id);
  const fullPost = response.data.data;

  // Now you have access to all post fields:
  // fullPost.title, fullPost.body, fullPost.author, etc.
}

Collection item webhook payloads

Data fields

Field	Type	Description	Required
`id`	string	Collection key identifier	Yes
`itemid`	string	API URI for retrieving the specific collection item	Yes
`label`	string	Display label for the collection item	Yes
`editor`	string	Full name of the editor who made the change	Yes
`timestamp`	string	Timestamp when webhook was generated	Yes
`locale`	string	Code of the locale a change applies to. Present for locale-scoped changes in localized organizations; absent otherwise	No
`status`	string	Current status: `draft`, `published`, or `deleted`	Yes

Example: collection item published

{
  "data": {
    "id": "products",
    "itemid": "/v2/content/?keys=products[_id=5678]",
    "label": "Wireless Headphones Pro",
    "editor": "Product Manager",
    "timestamp": "2024-01-15T13:45:00",
    "status": "published"
  },
  "webhook": {
    "event": "collectionitem.published",
    "target": "https://yourapp.com/webhooks/buttercms"
  }
}

Fetching full collection item data

The itemid field contains the API path to fetch the specific item:

// After receiving the webhook
const { data } = webhookPayload;

// The itemid contains the API query path
// e.g., "/v2/content/?keys=products[_id=5678]"

// Fetch the full item using the ButterCMS client
const butter = require('buttercms')('your-api-token');

// Extract the collection key and item ID
const collectionKey = data.id;  // "products"
const itemFilter = `[_id=${extractId(data.itemid)}]`;

const response = await butter.content.retrieve([collectionKey], {
  [collectionKey]: itemFilter
});

Media webhook payloads

media.videouploaded data fields

Field	Type	Description	Required
`id`	string (URI)	The uploaded video’s CDN URL	Yes

Example: Media video uploaded

{
  "data": {
    "id": "https://cdn.buttercms.com/video/company-promo.mp4"
  },
  "webhook": {
    "event": "media.videouploaded",
    "target": "https://yourapp.com/webhooks/buttercms"
  }
}

Localized content payloads

For Pages and Collection items, the locale field carries the code of the locale a change applies to.

Blog posts behave differently. The default-locale post.* events never carry a locale field; localized changes fire dedicated post.localization.* events that always include it. See Blog Post webhook payloads.

When `locale` is present

For organizations with localization enabled, the locale field indicates which locale triggered the event. Content edited in the default locale fires with that locale’s code:

{
  "data": {
    "id": "homepage",
    "locale": "es",
    ...
  }
}

When `locale` is absent

The field is omitted from the payload entirely for:

organizations that do not have localization enabled
delete events (page.delete, collectionitem.delete), which are not scoped to a locale

{
  "data": {
    "id": "homepage",
    ...
  }
}

Handling localized webhooks

app.post('/webhooks/buttercms', (req, res) => {
  const { data, webhook } = req.body;

  // Check whether the event is scoped to a locale
  if (data.locale) {
    // Locale-scoped change (includes the default locale in localized orgs)
    invalidateCache(data.id, data.locale);
  } else {
    // No locale scope: non-localized org, or a delete event
    invalidateCache(data.id, 'default');
  }

  res.status(200).json({ received: true });
});

Parsing webhook payloads

TypeScript interface

Define types for webhook payloads to ensure type safety:

interface WebhookMeta {
  event: string;
  target: string;
}

interface PageWebhookData {
  id: string;
  buttercms_id: number;
  page_type: string;
  editor: string;
  name: string;
  timestamp: string;
  locale?: string;
  status: 'draft' | 'published' | 'scheduled' | 'deleted';
  updated: string;
  published: string | null;
  scheduled: string | null;
}

interface BlogPostWebhookData {
  id: string;
  _id: number;
  locale?: string;
}

interface CollectionItemWebhookData {
  id: string;
  itemid: string;
  label: string;
  editor: string;
  timestamp: string;
  locale?: string;
  status: 'draft' | 'published' | 'deleted';
}

interface WebhookPayload<T> {
  data: T;
  webhook: WebhookMeta;
}

Event type detection

function handleWebhook(payload) {
  const { event } = payload.webhook;

  // Parse event type
  const [contentType, action] = event.split('.');

  switch (contentType) {
    case 'page':
      handlePageEvent(action, payload.data);
      break;
    case 'post':
      handlePostEvent(action, payload.data);
      break;
    case 'collectionitem':
      handleCollectionEvent(action, payload.data);
      break;
    case 'media':
      handleMediaEvent(action, payload.data);
      break;
  }
}

Overview

How-to recipes

Rendering complex field types

Webhooks and events

Third-party integrations

Performance

Content migration

Multi-site and environments

Localization and languages

SEO

Media CDN

Security and compliance

Payload structure

Webhook metadata

Page webhook payloads

Data fields

Example: Page published

Example: Page deleted

Blog Post webhook payloads

Data fields

Example: Blog Post published

Fetching full post data

Collection item webhook payloads

Data fields

Example: collection item published

Fetching full collection item data

Media webhook payloads

media.videouploaded data fields

Example: Media video uploaded

Localized content payloads

When `locale` is present

When `locale` is absent

Handling localized webhooks

Parsing webhook payloads

TypeScript interface

Event type detection

​Payload structure

​Webhook metadata

​Page webhook payloads

​Data fields

​Example: Page published

​Example: Page deleted

​Blog Post webhook payloads

​Data fields

​Example: Blog Post published

​Fetching full post data

​Collection item webhook payloads

​Data fields

​Example: collection item published

​Fetching full collection item data

​Media webhook payloads

​media.videouploaded data fields

​Example: Media video uploaded

​Localized content payloads

​When locale is present

​When locale is absent

​Handling localized webhooks

​Parsing webhook payloads

​TypeScript interface

​Event type detection

Payload structure

Webhook metadata

Page webhook payloads

Data fields

Example: Page published

Example: Page deleted

Blog Post webhook payloads

Data fields

Example: Blog Post published

Fetching full post data

Collection item webhook payloads

Data fields

Example: collection item published

Fetching full collection item data

Media webhook payloads

media.videouploaded data fields

Example: Media video uploaded

Localized content payloads

When `locale` is present

When `locale` is absent

Handling localized webhooks

Parsing webhook payloads

TypeScript interface

Event type detection