Channel Webhooks

Developers building third-party sales channels or multi-storefront capabilities might need notification when a channel in BigCommerce changes so that they can perform downstream actions required to set up or deactivate the channel. To facilitate this, we've added store/channel webhook events that fire when you create or update a channel. This article assumes that you're familiar with webhooks. It introduces channel-related events and is a reference for all BigCommerce channel webhook events and their callback payloads. For an introduction to webhooks on BigCommerce, see Webhooks Overview. For a more general introduction to webhooks, see Webhooks Overview.

To learn more about sales channels, see the Channels Overview. To learn more about how sales channels function in the context of multi-storefront or multi-channel sales, see the channels section of the Multi-Storefront Overview.

Creating a webhook

To create a webhook, send a request to the Create a webhook endpoint. Follow the process described in the Webhooks Overview, and include a channel_id where indicated to subscribe to that channel's events.

Example request: Create a webhook

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "scope": "store/channel/{channel_id}/cart/created", // replace {channel_id} with the actual channel_id
  "destination": "https://placeholder.ngrok.io/webhooks", // replace placeholder.ngrok.io with your HTTPS tunnel URL
  "is_active": true
}

The destination URL must be served on port 443; custom ports are not currently supported.
It can take up to one minute for a newly created webhook to work.

For information on creating a webhook, consult the creating a webhook section of the Webhooks Overview.

Callback structure

For webhook callback structure reference, see Webhook Events

Channel events

The following webhook events fire in response to actions that govern a store's sales channels:

Name / Scope	Description	Corresponding Endpoint
`store/channel/*`	Subscribes to all store/channel events	not applicable
`store/channel/created`	Fires when a channel is created using the control panel or the API	Create a channel
`store/channel/updated`	Fires when a channel is updated using the control panel or the API	Update a channel

Channel event payloads take the form that follows:

Example channel event payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1335335335,
 "scope": "store/channel/created",
 "data": {
    "type": "channel", // will always be channel
    "id": 2 // ID of the channel
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Channel update events

Changes to any of the following fields trigger a store/channel/updated event:

name
external_id
status
is_listable_from_ui
is_visible
is_enabled (to be deprecated)
config_meta

Carts

The following cart webhook events fire in response to actions that affect carts associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/cart/*`	Fires on all cart changes associated with the specified channel.	not applicable
`store/channel/{channel_id}/cart/created`	Fires on creation of a new cart associated with the specified channel.	Create a cart
`store/channel/{channel_id}/cart/updated`	Fires on update of a cart associated with the specified channel.	not applicable
`store/channel/{channel_id}/cart/deleted`	Fires on deletion of a cart associated with the specified channel.	Delete a cart
`store/channel/{channel_id}/cart/couponApplied`	Fires when a new coupon code associated with the specified channel is applied to a cart.	not applicable
`store/channel/{channel_id}/cart/abandoned`	Fires when a cart associated with the specified channel is abandoned.	not applicable
`store/channel/{channel_id}/cart/converted`	Fires when a cart associated with the specified channel is converted into an order.	not applicable

Cart payload objects take the form that follows:

Example cart payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/cart/created",
  "data": {
    "cart_id": "41696c19-486f-40a8-ae2a-389d5d24e0c9" // ID of the cart
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Cart line items

The following cart line item webhook events fire in response to actions that affect a cart items associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/cart/lineItem/*`	Fires on all cart line item changes associated with the specified channel.	not applicable
`store/channel/{channel_id}/cart/lineItem/created`	Fires when a new item is added to a cart associated with the specified channel.	Add cart line items
`store/channel/{channel_id}/cart/lineItem/updated`	Fires when an item's quantity or product options change in a cart associated with the specified channel.	Update Cart Line Item
`store/channel/{channel_id}/cart/lineItem/deleted`	Fires when items are deleted from any cart associated with the specified channel.	Delete cart line item

Cart line items payload objects take the form that follows:

Example cart line items profile payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/cart/lineItems/created",
  "data": {
    "cart_id": "41696c19-486f-40a8-ae2a-389d5d24e0c9", // ID of the cart
    "cart_item_id":  "af133539-0d83-464d-870d-776e2672e8f4" //ID of the cart line item
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/category/*`	Fires when subscribed to all category events for categories associated with the specified channel.	not applicable
`store/channel/{channel_id}/category/created`	Fires on creation of a new category in the category tree that is assigned to the specified channel.	Create categories
`store/channel/{channel_id}/category/updated`	Fires on update of a category within the category tree that is assigned to the specified channel.	Update categories
`store/channel/{channel_id}/category/deleted`	Fires when a category is removed from the category tree that is assigned to the specified channel.	Delete categories

Category trees

The following category tree webhook event fires in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/categoryTree/updated`	Fires when the specified channel's category tree is updated, created, or deleted.	Upsert category trees or Delete category trees

Category tree payload objects take the form that follows:

Example category tree payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/categoryTree/updated",
 "data": {
    "tree_id": 1 // ID of the category tree
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Customers

The following customers webhook event fires in response to customer changes:

Name / Scope	Description	Corresponding Endpoint
`store/customer/channel/login/access/updated`	Fires on update of any customer's login access.	Update a customer

Customers payload objects take the form that follows:

Example customers payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/customer/channel/login/access/updated",
 "data": {
    "customer_id": 22, // ID of the customer
    "channel_ids": [ // array of channels that the customer has accessed
      1
   ]
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Emails

The following emails webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/settings/emailStatus/updated`	Fires when an email status is updated per a specified channel.	Update transactional email settings
`store/channel/{channel_id}/settings/emailStatus/deleted`	Fires when an email status was deleted per a specified channel.	Update transactional email settings
`store/channel/{channel_id}/email/templates/updated`	Fires when an email template is updated per a specified channel.	Update a template
`store/channel/{channel_id}/email/templates/deleted`	Fires when an email template was deleted per a specified channel.	Delete email template override

Emails payload objects take the form that follows:

Example emails payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/settings/emailStatus/updated",
 "data": {
    "template_kind": "product_review_email"
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Metafields

The following metafield webhook events fire in response to actions that affect any channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/metafield/created/`	Fires when a channel metafield is created on any channel.	Create a channel metafield
`store/channel/metafield/updated`	Fires when any channel metafield is updated.	Update a channel metafield
`store/channel/metafield/deleted`	Fires when any channel metafield is deleted.	Delete a channel metafield

Metafields payload objects take the form that follows:

Example metafields payload object

{
  "store_id": "11111",
  "producer": "stores/abcde",
  "created_at": 1641641646,
  "scope": "store/channel/metafield/created",
  "data": {
    "metafield_id": 21,
    "resource_id": "1"    //channel ID
  },
  "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Notifications

The following notifications webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/notifications/abandonedCart/updated`	Fires when an abandoned cart notification is updated in the specified channel.	Update channel abandoned cart settings
`store/channel/{channel_id}/notifications/inventory/updated`	Fires when an inventory notification is updated in the specified channel.	Update inventory notifications settings

Notifications payload objects take the form that follows:

Example notifications payload object

{
  "store_id": "11111",
  "producer": "stores/abcde",
  "created_at": 1641641646,
  "scope": "store/channel/1/notifications/abandonedCart/updated",
  "data": {},
  "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Orders

The following orders webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/order/*`	Fires on all order events associated with the specified channel.	not applicable
`store/channel/{channel_id}/order/created`	Fires when an order associated with the specified channel is created.	Create an order
`store/channel/{channel_id}/order/updated`	Fires when an order associated with the specified channel is updated.	Update an order
`store/channel/{channel_id}/order/archived`	Fires when an order associated with the specified channel is archived.	Archive an order
`store/channel/{channel_id}/order/statusUpdated`	Fires when the status of an order associated with the specified channel is updated.	not applicable
`store/channel/{channel_id}/order/message/created`	Fires when an order message for an order associated with the specified channel is created using the control panel or the API	not applicable
`store/channel/{channel_id}/order/refund/created`	Fires when a refund is created for all or part of an order associated with the specified channel	not applicable

Order payload objects take the form that follows:

Example order payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/order/updated",
 "data": {
    "order_id": 127 // ID of the order
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Pages

The following page-related webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/page/created`	Fires on creation of a page associated with the specified channel.	Create pages
`store/channel/{channel_id}/page/updated`	Fires on update of a page associated with the specified channel.	Update pages

Web pages payload objects take the form that follows:

Example page payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/page/created",
  "data": {
    "page_id": 11 // ID of the page
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

For a complete reference of all BigCommerce webhook events and their callback payloads, see Webhook Events.

Price list assignments

The following price list assignment webhook event fires in response to price list assignment changes:

Name / Scope	Description	Corresponding Endpoint
`store/priceList/assignment/updated`	Fires when a price list assignment is assigned, reassigned, or unassigned.	Create price list assignments

Price list assignment payload objects take the form that follows:

Example price list assignment payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/priceList/assignment/updated",
 "data": {
    "price_list_id": 2,
    "channel_id": 1,
    "customer_group_id" : 3
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Product assignments

The following product assignment webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/product/assigned`	Fires when a product is assigned to the specified channel.	Create product channel assignments
`store/channel/{channel_id}/product/unassigned`	Fires when a product is removed from the specified channel.	Delete product channel assignments
`store/channel/{channel_id}/category/product/assigned`	Fires when a product is assigned to a category in the specified channel's category tree.	Create product category assignments
`store/channel/{channel_id}/category/product/unassigned`	Fires when a product is removed from a category in the specified channel's category tree.	Delete product category assignments

Product assignment payload objects take the form that follows:

Example product assignment payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/product/assigned",
 "data": {
    "product_id": 127 // ID of the product
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Routes

The following routes webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/settings/route/updated`	Fires on update of any route associated with the specified channel.	Update a site's routes or Update a site route

Routes payload objects take the form that follows:

Example route payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/settings/route/updated",
 "data": {
    "site_id": 1000
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Scripts

The following scripts webhook events fire in response to actions that affect a site associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoints
`store/channel/{channel_id}/script/created`	Fires on creation of any script associated with the specified channel.	Create a script
`store/channel/{channel_id}/script/updated`	Fires on update of any script associated with the specified channel.	Update a script

Scripts payload objects take the form that follows:

Example scripts payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/script/created",
 "data": {
   "uuid": "0187cc6c-cebf-45f9-93b8-7dd0a2e09774" // ID of the script
 },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Settings

The following settings webhook events fire in response to actions that affect a specific channel on a store:

Name / Scope	Description	Corresponding Endpoint
`store/channel/{channel_id}/settings/*`	Fires when subscribed to all settings updates for the specified channel.	not applicable
`store/channel/{channel_id}/settings/currency/updated`	Fires when currency associated with the specified channel is updated.	not applicable
`store/channel/{channel_id}/settings/profile/updated`	Fires when any of the global store profile settings are updated. Fires for both channel-specific profile settings changes and for changes to any global defaults that the specified channel inherits.	Update store profile settings
`store/channel/{channel_id}/settings/logo/updated`	Fires when any of the global logo settings are updated.	Update store logo settings
`store/channel/{channel_id}/settings/logo/image/updated`	Fires when any of the logo image settings that apply to the specified channel are updated.	not applicable
`store/channel/{channel_id}/settings/favicon/image/updated`	Fires when any of the favicon image settings that apply to the specified channel are updated.	not applicable
`store/channel/{channel_id}/settings/checkout/updated`	Fires when checkout settings that affect a specified channel are updated.	Update channel cart settings
`store/channel/{channel_id}/settings/SEO/updated`	Fires when SEO settings that affect the specified channel are updated.	Update storefront SEO settings
`store/channel/{channel_id}/settings/robots/updated`	Fires when search engine robot settings that affect the specified channel are updated.	Update robots.txt settings
`store/channel/{channel_id}/settings/category/updated`	Fires when category settings that affect the specified channel are updated.	Update storefront category settings
`store/channel/{channel_id}/settings/product/updated`	Fires when product settings that affect the specified channel are updated.	Update storefront product settings
`store/channel/{channel_id}/settings/catalog/updated`	Fires when catalog settings that affect the specified channel are updated.	Update catalog settings
`store/channel/{channel_id}/settings/security/updated`	Fires when security settings that affect the specified channel are updated.	Update storefront security settings
`store/channel/{channel_id}/settings/searchContextFilters/updated`	Fires when search context filters that affect the specified channel are updated.	Upsert Contextual Filters
`store/channel/{channel_id}/settings/defaultCustomerGroup/updated`	Fires when the default customer group associated with the specified channel is updated.	Update a customer group
`store/channel/{channel_id}/settings/customerPrivacy/updated`	Fires when customer privacy settings that affect the specified channel are updated.	Update customer settings per channel

Settings payload objects take the form that follows:

Example settings profile payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/settings/searchContextFilters/updated",
 "data": {
   "category_id": 29
 },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Sites

The following sites webhook events fire in response to actions that affect a site associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoints
`store/channel/{channel_id}/settings/site/updated`	Fires when a site associated with the specified channel is updated, created, or deleted.	Update a channel site, Update a site, Create a channel site, Create a site, Delete a channel site, or Delete a site
`store/channel/{channel_id}/settings/site/checkoutUrl/updated`	Fires when checkout domain per channel is updated.	Upsert a site's checkout URL
`store/channel/{channel_id}/settings/site/checkoutUrl/deleted`	Fires when checkout domain per channel is deleted.	Delete a site's checkout URL

Site payload objects take the form that follows:

Example site payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/settings/site/updated",
  "data": {
    "site_id": 1001 // ID of the site
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Social media links

The following social media links webhook event fires in response to actions that affect a site associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoints
`store/channel/{channel_id}/socialMediaLinks/updated`	Fires when a social media link associated with the specified channel is updated.	Not applicable

Social media link payload objects take the form that follows:

Example social media links payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/socialMediaLinks/updated",
 "data": {},
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Themes

The following themes webhook events fire in response to actions that affect a site associated with a specific channel on a store:

Name / Scope	Description	Corresponding Endpoints
`store/channel/{channel_id}/theme/configuration/created`	Fires when a theme associated with the specified channel is created.	Not applicable
`store/channel/{channel_id}/theme/configuration/activated`	Fires when a theme associated with the specified channel is published.	Not applicable

Theme payload objects take the form that follows:

Example theme payload object

{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/theme/configuration/created",
  "data": {
    "theme_id": "e3d82ce0-9bae-0133-0de7-525400970412",
    "variation_id": "f49489c0-8678-013a-2933-5227bc3d7181",
    "version_id": "f4337c30-8678-013a-2933-5227bc3d7181",
    "configuration_id": "2dc1c3f0-b2cf-013a-a341-2aac1278f99c"
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Resources

Did you find what you were looking for?

Events Inventory and location events