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
| Event | Trigger | Use Case |
|---|
page.published | Page is published or republished | Invalidate cache, trigger site rebuild, send notifications |
page.draft | Draft page is saved | Notify reviewers, update preview systems |
page.unpublished | Page is unpublished (taken offline) | Remove from search index, clear cache |
page.delete | Page is permanently deleted | Clean up related resources, update sitemaps |
page.all | Any page activity | General logging, comprehensive audit trails |
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
| Event | Trigger | Use Case |
|---|
post.published | Blog post is published | Share to social media, send newsletter, update RSS feed |
post.draft | Draft post is saved | Notify editors, update preview |
post.delete | Blog post is deleted | Remove from indexes, update feeds |
post.all | Any blog post activity | Comprehensive audit logging |
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.
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
| Event | Trigger | Use Case |
|---|
collectionitem.published | Item is published | Update product catalog, sync to external systems |
collectionitem.draft | Draft item is saved | Quality assurance notifications |
collectionitem.unpublished | Item is unpublished | Remove from listings, update availability |
collectionitem.delete | Item is deleted | Clean up references, archive data |
collectionitem.all | Any collection item activity | Full audit trail |
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.
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
| Event | Trigger | Use Case |
|---|
media.videouploaded | Video upload completes | Generate thumbnails, start transcoding, notify users |
Currently, only video uploads trigger webhook events. Image uploads do not generate webhook notifications.
Event timing
Understanding when events fire helps you build reliable integrations:
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
Conditional events
These events may fire immediately or be delayed:
*.published - Fires immediately for manual publish, or at scheduled time for scheduled contentmedia.videouploaded - Fires when video processing completes (may take time for large files)
Choosing the right events
For static site generators (Gatsby, Next.js, Hugo)
Subscribe to:
page.published - Rebuild site when pages changepost.published - Update blog when posts are publishedcollectionitem.published - Sync reference data
For cache invalidation
Subscribe to:
page.published, page.unpublished, page.deletepost.published, post.deletecollectionitem.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
ButterCMS does not guarantee the order of webhook deliveries. If your application depends on event ordering, implement idempotency and use timestamps from the payload to determine the correct sequence.
- Network latency variations
- Retry attempts for failed deliveries
- Concurrent content operations
