{ "openapi": "3.1.0", "info": { "title": "ButterCMS Webhooks API", "version": "2.0.0", "description": "Webhook event notifications sent by ButterCMS when content changes occur in your account.\n", "contact": { "email": "support@buttercms.com" }, "license": { "name": "ButterCMS Terms of Service", "url": "https://buttercms.com/terms/" } }, "servers": [ { "url": "https://api.buttercms.com/v2", "description": "ButterCMS API v2" } ], "tags": [ { "name": "Page events", "description": "Webhook event notifications sent by ButterCMS when page content changes occur in your account.\n" }, { "name": "Post events", "description": "Webhook event notifications sent by ButterCMS when blog post changes occur in your account.\n" }, { "name": "Collection events", "description": "Webhook event notifications sent by ButterCMS when collection item changes occur in your account.\n" }, { "name": "Media events", "description": "Webhook event notifications sent by ButterCMS when media changes occur in your account.\n" } ], "paths": {}, "components": { "securitySchemes": { "readTokenAuthQuery": { "type": "apiKey", "in": "query", "name": "auth_token", "description": "Pass your API token via the `auth_token` parameter on every request: `?auth_token=your_read_api_token`.\n\nYou can access your API token from your settings page.\n\nRequests made with a missing or invalid token will get a 401 Unauthorized response. All requests must be made over HTTPS.\n" }, "readTokenAuthHeader": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Set the `Authorization` header to `Token your_read_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nNote: The header value includes the `Token` prefix.\n\nYou can access your API token from your settings page.\n" }, "writeTokenAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Write-enabled API token required for creating content.\n\nThe API token you use for reading from the ButterCMS API will not allow you to create content in the API. For this you will need to use a different write-enabled token. Chat or email support@buttercms.com to get yours.\n\nSet the `Authorization` header to `Token your_write_api_token`.\n\nExample: `Authorization: Token abc123def456`\n\nYour write-enabled token should never be used anywhere it would be exposed, e.g. in client-side JavaScript.\n" } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "detail": { "type": "string", "description": "Error message describing what went wrong", "example": "Authentication credentials were not provided" } } }, "PageWebhookData": { "type": "object", "description": "Webhook data payload for page events", "properties": { "id": { "type": "string", "description": "Page slug", "example": "example-page-slug" }, "buttercms_id": { "type": "integer", "description": "Page numeric ID", "example": 1234 }, "page_type": { "type": "string", "description": "Page type key, or '*' for single pages", "example": "news" }, "editor": { "type": "string", "description": "Full name of the editor who made the change", "example": "John Doe" }, "name": { "type": "string", "description": "Human-readable page name", "example": "Example Page" }, "timestamp": { "type": "string", "description": "Current timestamp when webhook was generated", "example": "2024-01-15T18:11:09" }, "locale": { "type": [ "string", "null" ], "description": "Locale code for localized content, null for default locale", "example": "en" }, "status": { "type": "string", "description": "Current page status", "enum": [ "draft", "published", "scheduled", "deleted" ], "example": "published" }, "updated": { "type": "string", "format": "date-time", "description": "Last updated timestamp in ISO 8601 format", "example": "2024-01-15T18:11:09.791061Z" }, "published": { "type": [ "string", "null" ], "format": "date-time", "description": "Published timestamp in ISO 8601 format, null if not published", "example": "2024-01-15T18:10:00.000000Z" }, "scheduled": { "type": [ "string", "null" ], "format": "date-time", "description": "Scheduled publication timestamp in ISO 8601 format, null if not scheduled", "example": null } }, "required": [ "id", "buttercms_id", "page_type", "editor", "name", "timestamp", "status", "updated" ] }, "CollectionItemWebhookData": { "type": "object", "description": "Webhook data payload for collection item events", "properties": { "id": { "type": "string", "description": "Collection key identifier", "example": "your_collection" }, "itemid": { "type": "string", "description": "API URI for retrieving the specific collection item", "example": "/v2/content/?keys=your_collection[_id=1234]" }, "label": { "type": "string", "description": "Display label for the collection item", "example": "Your Collection Item" }, "editor": { "type": "string", "description": "Full name of the editor who made the change", "example": "John Doe" }, "timestamp": { "type": "string", "description": "Current timestamp when webhook was generated", "example": "2024-01-15T18:11:09" }, "locale": { "type": [ "string", "null" ], "description": "Locale code for localized content, null for default locale", "example": "en" }, "status": { "type": "string", "description": "Current collection item status", "enum": [ "draft", "published", "deleted" ], "example": "published" } }, "required": [ "id", "itemid", "label", "editor", "timestamp" ] }, "BlogPostWebhookData": { "type": "object", "description": "Webhook data payload for blog post events", "properties": { "id": { "type": "string", "description": "Blog post slug", "example": "example-blog-post-slug" }, "_id": { "type": "integer", "description": "Blog post numeric ID", "example": 1234 } }, "required": [ "id", "_id" ] }, "BlogPostLocalizedWebhookData": { "type": "object", "description": "Webhook data payload for localized blog post events. Includes locale to identify which locale variant triggered the event.", "properties": { "id": { "type": "string", "description": "Blog post slug", "example": "example-blog-post-slug" }, "_id": { "type": "integer", "description": "Blog post numeric ID", "example": 1234 }, "locale": { "type": "string", "description": "Locale of the blog post variant that triggered the event", "example": "en" } }, "required": [ "id", "_id", "locale" ] }, "WebhookMeta": { "type": "object", "description": "Webhook metadata included in all webhook payloads", "properties": { "event": { "type": "string", "enum": [ "post.all", "post.published", "post.draft", "post.delete", "post.localization.published", "post.localization.draft", "post.localization.delete", "page.all", "page.published", "page.draft", "page.delete", "page.unpublished", "collectionitem.all", "collectionitem.published", "collectionitem.draft", "collectionitem.delete", "collectionitem.unpublished", "media.videouploaded", "media.updated" ], "description": "The event type that triggered this webhook" }, "target": { "type": "string", "format": "uri", "description": "The webhook endpoint URL that received this notification" } }, "required": [ "event", "target" ] } } }, "webhooks": { "page-published": { "post": { "description": "Triggered when a page is published or republished.\n\nThis event fires when:\n- A draft page is published for the first time\n- An already published page is republished after changes\n- A scheduled page is automatically published\n", "x-mint": { "metadata": { "description": "Triggered when a page is published or republished, including scheduled publishing." }, "content": "Triggered when a page is published or republished.\n\nThis event fires when:\n- A draft page is published for the first time\n- An already published page is republished after changes\n- A scheduled page is automatically published\n" }, "operationId": "webhookPagePublished", "summary": "Page Published", "tags": [ "Page events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "page.published" ] } } } ] } } }, "examples": { "page_published": { "summary": "Page published", "value": { "data": { "id": "product-launch", "buttercms_id": 5678, "page_type": "landing", "editor": "Marketing Team", "name": "Product Launch Landing Page", "timestamp": "2024-01-15T14:30:00", "locale": null, "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" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "page-draft-saved": { "post": { "description": "Triggered when a draft page version is saved.\n\nThis event fires when:\n- A new page is created and saved as draft\n- An existing draft page is updated and saved\n- A published page is updated but not yet republished\n", "x-mint": { "metadata": { "description": "Triggered when a draft page version is saved, including on creation, update, or unpublished changes." }, "content": "Triggered when a draft page version is saved.\n\nThis event fires when:\n- A new page is created and saved as draft\n- An existing draft page is updated and saved\n- A published page is updated but not yet republished\n" }, "operationId": "webhookPageDraftSaved", "summary": "Page Draft Saved", "tags": [ "Page events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "page.draft" ] } } } ] } } }, "examples": { "draft_saved": { "summary": "Page draft saved", "value": { "data": { "id": "upcoming-event", "buttercms_id": 9012, "page_type": "event", "editor": "Event Coordinator", "name": "Upcoming Conference Event", "timestamp": "2024-01-15T16:45:00", "locale": "en", "status": "draft", "updated": "2024-01-15T16:45:00.987654Z", "published": null, "scheduled": "2024-02-01T09:00:00.000000Z" }, "webhook": { "event": "page.draft", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "page-unpublished": { "post": { "description": "Triggered when a published page is unpublished (but not deleted).\n\nThis event fires when:\n- A published page is deliberately unpublished but kept in the system\n- A page is temporarily taken offline without permanent deletion\n", "x-mint": { "metadata": { "description": "Triggered when a published page is unpublished but not deleted." }, "content": "Triggered when a published page is unpublished (but not deleted).\n\nThis event fires when:\n- A published page is deliberately unpublished but kept in the system\n- A page is temporarily taken offline without permanent deletion\n" }, "operationId": "webhookPageUnpublished", "summary": "Page Unpublished", "tags": [ "Page events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "page.unpublished" ] } } } ] } } }, "examples": { "page_unpublished": { "summary": "Page unpublished", "value": { "data": { "id": "maintenance-notice", "buttercms_id": 7890, "page_type": "notice", "editor": "Site Administrator", "name": "Maintenance Notice", "timestamp": "2024-01-15T22:00:00", "locale": null, "status": "draft", "updated": "2024-01-15T22:00:00.333444Z", "published": null, "scheduled": null }, "webhook": { "event": "page.unpublished", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "page-deleted": { "post": { "description": "Triggered when a published page is permanently deleted.\n\nThis event fires when:\n- A page is permanently removed from the system\n- A page is moved to trash and then permanently deleted\n", "x-mint": { "metadata": { "description": "Triggered when a published page is permanently deleted or moved to trash." }, "content": "Triggered when a published page is permanently deleted.\n\nThis event fires when:\n- A page is permanently removed from the system\n- A page is moved to trash and then permanently deleted\n" }, "operationId": "webhookPageDeleted", "summary": "Page Deleted", "tags": [ "Page events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "page.delete" ] } } } ] } } }, "examples": { "page_deleted": { "summary": "Page deleted", "value": { "data": { "id": "old-promotion", "buttercms_id": 3456, "page_type": "promo", "editor": "Content Manager", "name": "Old Promotion Page", "timestamp": "2024-01-15T20:15:00", "locale": null, "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" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "page-any-activity": { "post": { "description": "Triggered when any activity occurs on a page (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all page changes, useful for comprehensive page monitoring and cache invalidation across all page types.\n", "x-mint": { "metadata": { "description": "Triggered when any activity occurs on a page, including create, update, publish, unpublish, and delete events." }, "content": "Triggered when any activity occurs on a page (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all page changes, useful for comprehensive page monitoring and cache invalidation across all page types.\n" }, "operationId": "webhookPageAll", "summary": "Page Any Activity", "tags": [ "Page events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PageWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "page.all" ] } } } ] } } }, "examples": { "page_updated": { "summary": "Page updated", "value": { "data": { "id": "company-news", "buttercms_id": 1234, "page_type": "news", "editor": "Jane Editor", "name": "Company News Page", "timestamp": "2024-01-15T18:11:09", "locale": "en", "status": "published", "updated": "2024-01-15T18:11:09.791061Z", "published": "2024-01-15T18:10:00.000000Z", "scheduled": null }, "webhook": { "event": "page.all", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-published": { "post": { "description": "Triggered when a blog post is published or republished.\n\nThis event fires when:\n- A draft blog post is published for the first time\n- An already published post is republished after changes\n- A scheduled post is automatically published\n", "x-mint": { "metadata": { "description": "Triggered when a blog post is published or republished, including scheduled publishing." }, "content": "Triggered when a blog post is published or republished.\n\nThis event fires when:\n- A draft blog post is published for the first time\n- An already published post is republished after changes\n- A scheduled post is automatically published\n" }, "operationId": "webhookPostPublished", "summary": "Blog Post Published", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.published" ] } } } ] } } }, "examples": { "post_published": { "summary": "Blog post published", "value": { "data": { "id": "announcing-new-features", "_id": 5678 }, "webhook": { "event": "post.published", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-draft-saved": { "post": { "description": "Triggered when a draft blog post is saved.\n\nThis event fires when:\n- A new blog post is created and saved as draft\n- An existing draft is updated and saved\n- A published post is updated and saved as draft (effectively unpublishing)\n", "x-mint": { "metadata": { "description": "Triggered when a blog post draft is saved, including on creation, update, or status change." }, "content": "Triggered when a draft blog post is saved.\n\nThis event fires when:\n- A new blog post is created and saved as draft\n- An existing draft is updated and saved\n- A published post is updated and saved as draft (effectively unpublishing)\n" }, "operationId": "webhookPostDraft", "summary": "Blog Post Draft Saved", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.draft" ] } } } ] } } }, "examples": { "draft_saved": { "summary": "Draft blog post saved", "value": { "data": { "id": "work-in-progress-post", "_id": 9012 }, "webhook": { "event": "post.draft", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-deleted": { "post": { "description": "Triggered when a published blog post is unpublished or deleted.\n\nThis event fires when:\n- A published blog post is moved to trash\n- A published blog post is permanently deleted\n- A published blog post is unpublished (soft delete)\n", "x-mint": { "metadata": { "description": "Triggered when a published blog post is unpublished or permanently deleted." }, "content": "Triggered when a published blog post is unpublished or deleted.\n\nThis event fires when:\n- A published blog post is moved to trash\n- A published blog post is permanently deleted\n- A published blog post is unpublished (soft delete)\n" }, "operationId": "webhookPostDelete", "summary": "Blog Post Deleted", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.delete" ] } } } ] } } }, "examples": { "post_deleted": { "summary": "Blog post deleted", "value": { "data": { "id": "outdated-announcement", "_id": 3456 }, "webhook": { "event": "post.delete", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-any-activity": { "post": { "description": "Triggered when any activity occurs on a blog post (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all blog post changes, making it useful for general blog post monitoring and cache invalidation.\n", "x-mint": { "metadata": { "description": "Triggered when any activity occurs on a blog post, including create, update, publish, unpublish, and delete events." }, "content": "Triggered when any activity occurs on a blog post (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all blog post changes, making it useful for general blog post monitoring and cache invalidation.\n" }, "operationId": "webhookPostAll", "summary": "Blog Post Any Activity", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.all" ] } } } ] } } }, "examples": { "post_updated": { "summary": "Blog post updated", "value": { "data": { "id": "api-development-best-practices", "_id": 1234 }, "webhook": { "event": "post.all", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-locale-published": { "post": { "description": "Triggered when a localized blog post is published or republished.\n\nThis event fires when:\n- A draft blog post in a specific locale is published for the first time\n- An already published localized post is republished after changes\n- A scheduled localized post is automatically published\n\nThe payload includes the `locale` field identifying which locale variant was published.\n", "x-mint": { "metadata": { "description": "Triggered when a localized blog post is published or republished. Includes locale in the payload." }, "content": "Triggered when a localized blog post is published or republished.\n\nThis event fires when:\n- A draft blog post in a specific locale is published for the first time\n- An already published localized post is republished after changes\n- A scheduled localized post is automatically published\n\nThe payload includes the `locale` field identifying which locale variant was published.\n" }, "operationId": "webhookPostLocalePublished", "summary": "Localized Blog Post Published", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostLocalizedWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.localization.published" ] } } } ] } } }, "examples": { "locale_post_published": { "summary": "Localized blog post published", "value": { "data": { "id": "announcing-new-features", "_id": 5678, "locale": "es" }, "webhook": { "event": "post.localization.published", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-locale-draft-saved": { "post": { "description": "Triggered when a localized draft blog post is saved.\n\nThis event fires when:\n- A new blog post in a specific locale is created and saved as draft\n- An existing localized draft is updated and saved\n- A published localized post is updated and saved as draft\n\nThe payload includes the `locale` field identifying which locale variant was saved.\n", "x-mint": { "metadata": { "description": "Triggered when a localized blog post draft is saved. Includes locale in the payload." }, "content": "Triggered when a localized draft blog post is saved.\n\nThis event fires when:\n- A new blog post in a specific locale is created and saved as draft\n- An existing localized draft is updated and saved\n- A published localized post is updated and saved as draft\n\nThe payload includes the `locale` field identifying which locale variant was saved.\n" }, "operationId": "webhookPostLocaleDraft", "summary": "Localized Blog Post Draft Saved", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostLocalizedWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.localization.draft" ] } } } ] } } }, "examples": { "locale_draft_saved": { "summary": "Localized draft blog post saved", "value": { "data": { "id": "work-in-progress-post", "_id": 9012, "locale": "fr" }, "webhook": { "event": "post.localization.draft", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "blog-post-locale-deleted": { "post": { "description": "Triggered when a localized blog post is unpublished or deleted.\n\nThis event fires when:\n- A published localized blog post is moved to trash\n- A published localized blog post is permanently deleted\n- A published localized blog post is unpublished\n\nThe payload includes the `locale` field identifying which locale variant was deleted.\n", "x-mint": { "metadata": { "description": "Triggered when a localized blog post is unpublished or deleted. Includes locale in the payload." }, "content": "Triggered when a localized blog post is unpublished or deleted.\n\nThis event fires when:\n- A published localized blog post is moved to trash\n- A published localized blog post is permanently deleted\n- A published localized blog post is unpublished\n\nThe payload includes the `locale` field identifying which locale variant was deleted.\n" }, "operationId": "webhookPostLocaleDelete", "summary": "Localized Blog Post Deleted", "tags": [ "Post events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BlogPostLocalizedWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "post.localization.delete" ] } } } ] } } }, "examples": { "locale_post_deleted": { "summary": "Localized blog post deleted", "value": { "data": { "id": "outdated-announcement", "_id": 3456, "locale": "de" }, "webhook": { "event": "post.localization.delete", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "collection-item-published": { "post": { "description": "Triggered when a collection item is published or republished.\n\nThis event fires when:\n- A draft collection item is published for the first time\n- An already published item is republished after changes\n- A scheduled item is automatically published\n", "x-mint": { "metadata": { "description": "Triggered when a collection item is published or republished, including scheduled publishing." }, "content": "Triggered when a collection item is published or republished.\n\nThis event fires when:\n- A draft collection item is published for the first time\n- An already published item is republished after changes\n- A scheduled item is automatically published\n" }, "operationId": "webhookCollectionItemPublished", "summary": "Collection Item Published", "tags": [ "Collection events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionItemWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "collectionitem.published" ] } } } ] } } }, "examples": { "item_published": { "summary": "Collection item published", "value": { "data": { "id": "products", "itemid": "/v2/content/?keys=products[_id=5678]", "label": "Wireless Headphones Pro", "editor": "Product Manager", "timestamp": "2024-01-15T13:45:00", "locale": null, "status": "published" }, "webhook": { "event": "collectionitem.published", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "collection-item-draft-saved": { "post": { "description": "Triggered when a collection item draft is saved.\n\nThis event fires when:\n- A new collection item is created and saved as draft\n- An existing draft item is updated and saved\n- A published item is updated but not yet republished\n", "x-mint": { "metadata": { "description": "Triggered when a collection item draft is saved, including on creation, update, or unpublished changes." }, "content": "Triggered when a collection item draft is saved.\n\nThis event fires when:\n- A new collection item is created and saved as draft\n- An existing draft item is updated and saved\n- A published item is updated but not yet republished\n" }, "operationId": "webhookCollectionItemDraft", "summary": "Collection Item Draft Saved", "tags": [ "Collection events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionItemWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "collectionitem.draft" ] } } } ] } } }, "examples": { "draft_saved": { "summary": "Collection item draft saved", "value": { "data": { "id": "events", "itemid": "/v2/content/?keys=events[_id=9012]", "label": "Annual Developer Conference 2024", "editor": "Event Planner", "timestamp": "2024-01-15T15:20:00", "locale": "en", "status": "draft" }, "webhook": { "event": "collectionitem.draft", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "collection-item-unpublished": { "post": { "description": "Triggered when a collection item is unpublished (but not deleted).\n\nThis event fires when:\n- A published collection item is deliberately unpublished but kept in the system\n- An item is temporarily taken offline without permanent deletion\n", "x-mint": { "metadata": { "description": "Triggered when a collection item is unpublished but not deleted." }, "content": "Triggered when a collection item is unpublished (but not deleted).\n\nThis event fires when:\n- A published collection item is deliberately unpublished but kept in the system\n- An item is temporarily taken offline without permanent deletion\n" }, "operationId": "webhookCollectionItemUnpublished", "summary": "Collection Item Unpublished", "tags": [ "Collection events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionItemWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "collectionitem.unpublished" ] } } } ] } } }, "examples": { "item_unpublished": { "summary": "Collection item unpublished", "value": { "data": { "id": "promotions", "itemid": "/v2/content/?keys=promotions[_id=7890]", "label": "Holiday Sale 2023", "editor": "Marketing Manager", "timestamp": "2024-01-15T21:00:00", "locale": "en", "status": "draft" }, "webhook": { "event": "collectionitem.unpublished", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "collection-item-deleted": { "post": { "description": "Triggered when a collection item is deleted.\n\nThis event fires when:\n- A collection item is permanently removed from the system\n- A collection item is moved to trash and then permanently deleted\n", "x-mint": { "metadata": { "description": "Triggered when a collection item is permanently deleted or moved to trash." }, "content": "Triggered when a collection item is deleted.\n\nThis event fires when:\n- A collection item is permanently removed from the system\n- A collection item is moved to trash and then permanently deleted\n" }, "operationId": "webhookCollectionItemDelete", "summary": "Collection Item Deleted", "tags": [ "Collection events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionItemWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "collectionitem.delete" ] } } } ] } } }, "examples": { "item_deleted": { "summary": "Collection item deleted", "value": { "data": { "id": "testimonials", "itemid": "/v2/content/?keys=testimonials[_id=3456]", "label": "Customer Review - ABC Corp", "editor": "Content Moderator", "timestamp": "2024-01-15T19:30:00", "locale": null, "status": "deleted" }, "webhook": { "event": "collectionitem.delete", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "collection-item-any-activity": { "post": { "description": "Triggered when any activity occurs on a collection item (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all collection item changes, useful for comprehensive content monitoring across all collections.\n", "x-mint": { "metadata": { "description": "Triggered when any activity occurs on a collection item, including create, update, publish, unpublish, and delete events." }, "content": "Triggered when any activity occurs on a collection item (create, update, publish, unpublish, delete).\n\nThis is a catch-all event that fires for all collection item changes, useful for comprehensive content monitoring across all collections.\n" }, "operationId": "webhookCollectionItemAll", "summary": "Collection Item Any Activity", "tags": [ "Collection events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionItemWebhookData" }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "collectionitem.all" ] } } } ] } } }, "examples": { "item_updated": { "summary": "Collection item updated", "value": { "data": { "id": "team_members", "itemid": "/v2/content/?keys=team_members[_id=1234]", "label": "John Smith - Senior Developer", "editor": "HR Manager", "timestamp": "2024-01-15T11:30:00", "locale": "en", "status": "published" }, "webhook": { "event": "collectionitem.all", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "media-video-uploaded": { "post": { "description": "Triggered when a video file is uploaded to the media library.\n\nThis event fires when:\n- A new video file is uploaded to ButterCMS media library\n- Video processing is completed and the file is available\n", "x-mint": { "metadata": { "description": "Triggered when a video file is uploaded to the media library and processing is complete." }, "content": "Triggered when a video file is uploaded to the media library.\n\nThis event fires when:\n- A new video file is uploaded to ButterCMS media library\n- Video processing is completed and the file is available\n" }, "operationId": "webhookMediaVideoUploaded", "summary": "Media Video Uploaded", "tags": [ "Media events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uri", "description": "The uploaded video's CDN URL" } } }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "media.videouploaded" ] } } } ] } } }, "examples": { "video_uploaded": { "summary": "Video uploaded to media library", "value": { "data": { "id": "https://cdn.buttercms.com/video/company-promo.mp4" }, "webhook": { "event": "media.videouploaded", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } }, "media-updated": { "post": { "description": "Triggered when the file behind an existing media asset changes.\n\nThis event fires when:\n- An image is edited with the built-in image editor (crop, rotate, circle)\n- A media file is replaced with a new file\n- A media file is restored to its original version\n\nThe `cdn_url` does not change when this happens. Pages that reference it\nstart serving the new file without any other signal, so subscribe to this\nevent if you rebuild a static site or purge a cache when content changes.\n\nEditing an image from a content field, a page's media field, or a blog\npost's featured image creates a new media asset and leaves the original\none untouched, so it does not fire this event.\n", "x-mint": { "metadata": { "description": "Triggered when a media file is edited, replaced, or restored. The cdn_url stays the same while the file behind it changes." }, "content": "Triggered when the file behind an existing media asset changes.\n\nThis event fires when:\n- An image is edited with the built-in image editor (crop, rotate, circle)\n- A media file is replaced with a new file\n- A media file is restored to its original version\n\nThe `cdn_url` does not change when this happens. Pages that reference it\nstart serving the new file without any other signal, so subscribe to this\nevent if you rebuild a static site or purge a cache when content changes.\n\nEditing an image from a content field, a page's media field, or a blog\npost's featured image creates a new media asset and leaves the original\none untouched, so it does not fire this event.\n" }, "operationId": "webhookMediaUpdated", "summary": "Media Updated", "tags": [ "Media events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uri", "description": "The asset's CDN URL (unchanged by the update)" }, "media_id": { "type": "integer", "description": "Internal ID of the media asset" }, "name": { "type": "string", "description": "The asset's name as shown in the Media Library (unchanged by the update)" } } }, "webhook": { "allOf": [ { "$ref": "#/components/schemas/WebhookMeta" }, { "properties": { "event": { "enum": [ "media.updated" ] } } } ] } } }, "examples": { "media_updated": { "summary": "Image edited or replaced", "value": { "data": { "id": "https://cdn.buttercms.com/AbCdEf123XyZ", "media_id": 12345, "name": "hero-image.webp" }, "webhook": { "event": "media.updated", "target": "https://yourapp.com/webhooks/buttercms" } } } } } } }, "responses": { "200": { "description": "Return a 200 status to indicate that the data was received successfully" } }, "security": [] } } } }