Webhook event types

ButterCMS automatically sends webhook notifications for various content events including blog posts, pages, and collection items. These events enable real-time integration with your applications, triggering immediate responses to content changes. Event Types: Webhooks are triggered for create, update, publish, unpublish, and delete operations across all content types. Delivery Method: All webhook events are delivered as HTTP POST requests to your configured endpoint URLs, with JSON payloads containing event metadata and complete content data.

​

Page events

​

page.published

Triggered when a page is published or republished. This event fires when:

• A draft page is published for the first time
• An already published page is republished after changes
• A scheduled page is automatically published

​

page.draft

Triggered when a draft page is created or updated. This event fires when:

• A new page is created and saved as draft
• An existing draft page is modified
• A published page has draft changes saved

​

page.unpublished

Triggered when a published page is unpublished. This event fires when:

• A published page is manually unpublished
• A page is reverted from published to draft state

​

page.delete

Triggered when a published page is permanently deleted. This event fires when:

• A page is permanently removed from the system
• A page is moved to trash and then permanently deleted

​

page.all

Triggered for any page-related activity. This is a catch-all event useful for logging or when you need to track all page changes regardless of type.

​

Blog Post events

​

post.published

Triggered when a blog post is published or republished. This event fires when:

• A draft blog post is published for the first time
• An already published post is republished after changes
• A scheduled post is automatically published

​

post.draft

Triggered when a draft blog post is created or updated. This event fires when:

• A new blog post is created and saved as draft
• An existing draft post is modified

​

post.delete

Triggered when a blog post is permanently deleted.

​

Localized Blog Post events

When localization is enabled, changes to a non-default locale of a blog post fire dedicated post.localization.* events (in addition to the default-locale post.* events, which fire for the organization’s default locale). Subscribe to these when you need to react to a specific locale being published, drafted, or removed. The payload for these events includes a locale field identifying which locale changed. See Localized content payloads.

​

Collection item events

​

collectionitem.published

Triggered when a collection item is published or republished. This event fires when:

• A draft collection item is published for the first time
• An already published item is republished after changes
• A scheduled item is automatically published

​

collectionitem.draft

Triggered when a draft collection item is created or updated.

​

collectionitem.unpublished

Triggered when a published collection item is unpublished.

​

collectionitem.delete

Triggered when a collection item is permanently deleted.

​

collectionitem.all

Triggered for any collection item activity.

​

Media events

​

media.videouploaded

Triggered when a video file upload is completed. This event fires when:

• A video file finishes uploading to the media library
• Video processing is complete and the file is ready for use

​

media.updated

Triggered when the file behind an existing media asset changes. This event fires when:

• An image is edited with the built-in image editor (crop, rotate, circle)
• A media file is replaced with a new file
• A media file is restored to its original version

The cdn_url does not change when this happens. Pages that reference it start serving the new file without any other signal, so subscribe to this event if you rebuild a static site or purge a cache when content changes.

​

Event timing

Understanding when events fire helps you build reliable integrations:

​

Immediate events

These events fire immediately when the action is taken:

• *.draft - Fires immediately when content is saved
• *.delete - Fires immediately when content is deleted
• *.unpublished - Fires immediately when content is unpublished
• media.updated - Fires immediately when a media file is edited, replaced, or restored

​

Conditional events

These events may fire immediately or be delayed:

• *.published - Fires immediately for manual publish, or at scheduled time for scheduled content
• media.videouploaded - Fires when video processing completes (may take time for large files)

​

Choosing the right events

​

For static site generators (Next.js, Astro, Hugo)

Subscribe to:

• page.published - Rebuild site when pages change
• post.published - Update blog when posts are published
• collectionitem.published - Sync reference data
• media.updated - Rebuild when an image is edited or replaced (the URL stays the same, only the file changes)

​

For cache invalidation

Subscribe to:

• page.published, page.unpublished, page.delete
• post.published, post.delete
• collectionitem.published, collectionitem.unpublished

​

For search index updates

Subscribe to:

• All *.published events - Add/update content in search
• All *.delete events - Remove content from search
• All *.unpublished events - Remove from public search

​

For notifications and alerts

Subscribe to:

• *.draft events - Notify reviewers of new content
• *.published events - Alert subscribers of new content
• *.delete events - Warn about content removal

​

Event delivery order

Events may arrive out of order due to:

• Network latency variations
• Retry attempts for failed deliveries
• Concurrent content operations