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
`store/channel/*`	Subscribes to all store/channel events
`store/channel/created`	Fires when a channel is created using the control panel or the API. The corresponding endpoint is Create a channel.
`store/channel/updated`	Fires when a channel is updated using the control panel or the API. The corresponding endpoint is 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)

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
`store/channel/{channel_id}/cart/*`	Fires on all cart changes associated with the specified channel.
`store/channel/{channel_id}/cart/created`	Fires on creation of a new cart associated with the specified channel. The corresponding endpoint is Create a cart.
`store/channel/{channel_id}/cart/updated`	Fires on update of a cart associated with the specified channel.
`store/channel/{channel_id}/cart/deleted`	Fires on deletion of a cart associated with the specified channel. The corresponding endpoint is 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.
`store/channel/{channel_id}/cart/abandoned`	Fires when a cart associated with the specified channel is abandoned.
`store/channel/{channel_id}/cart/converted`	Fires when a cart associated with the specified channel is converted into an order.

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
`store/channel/{channel_id}/cart/lineItem/*`	Fires on all cart line item changes associated with the specified channel.
`store/channel/{channel_id}/cart/lineItem/created`	Fires when a new item is added to a cart associated with the specified channel. The corresponding endpoint is 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. The corresponding endpoint is Update Cart Line Item.
`store/channel/{channel_id}/cart/lineItem/deleted`	Fires when items are deleted from any cart associated with the specified channel. The corresponding endpoint is 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
`store/channel/{channel_id}/category/*`	Fires when subscribed to all category events for categories associated with the specified channel.
`store/channel/{channel_id}/category/created`	Fires on creation of a new category in the category tree that is assigned to the specified channel. The corresponding endpoint is 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. The corresponding endpoint is 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. The corresponding endpoint is 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
`store/channel/{channel_id}/categoryTree/updated`	Fires when the specified channel's category tree is updated, created, or deleted. The corresponding endpoint is 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
`store/customer/channel/login/access/updated`	Fires on update of any customer's login access. The corresponding endpoint is 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
`store/channel/{channel_id}/settings/emailStatus/updated`	Fires when an email status is updated per a specified channel. The corresponding endpoint is Update transactional email settings.
`store/channel/{channel_id}/settings/emailStatus/deleted`	Fires when an email status was deleted per a specified channel. The corresponding endpoint is Update transactional email settings.
`store/channel/{channel_id}/email/templates/updated`	Fires when an email template is updated per a specified channel. The corresponding endpoint is Update a template.
`store/channel/{channel_id}/email/templates/deleted`	Fires when an email template was deleted per a specified channel. The corresponding endpoint is 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
`store/channel/metafield/created/`	Fires when a channel metafield is created on any channel. The corresponding endpoint is Create a channel metafield.
`store/channel/metafield/updated`	Fires when any channel metafield is updated. The corresponding endpoint is Update a channel metafield.
`store/channel/metafield/deleted`	Fires when any channel metafield is deleted. The corresponding endpoint is 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
`store/channel/{channel_id}/notifications/abandonedCart/updated`	Fires when an abandoned cart notification is updated in the specified channel. The corresponding endpoint is Update channel abandoned cart settings.
`store/channel/{channel_id}/notifications/inventory/updated`	Fires when an inventory notification is updated in the specified channel. The corresponding endpoint is 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
`store/channel/{channel_id}/order/*`	Fires on all order events associated with the specified channel.
`store/channel/{channel_id}/order/created`	Fires when an order associated with the specified channel is created. The corresponding endpoint is Create an order.
`store/channel/{channel_id}/order/updated`	Fires when an order associated with the specified channel is updated. The corresponding endpoint is Update an order.
`store/channel/{channel_id}/order/archived`	Fires when an order associated with the specified channel is archived. The corresponding endpoint is Archive an order.
`store/channel/{channel_id}/order/statusUpdated`	Fires when the status of an order associated with the specified channel is updated.
`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
`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

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
`store/channel/{channel_id}/page/created`	Fires on creation of a page associated with the specified channel. The corresponding endpoint is Create pages.
`store/channel/{channel_id}/page/updated`	Fires on update of a page associated with the specified channel. The corresponding endpoint is 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
`store/priceList/assignment/updated`	Fires when a price list assignment is assigned, reassigned, or unassigned. The corresponding endpoint is 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
`store/channel/{channel_id}/product/assigned`	Fires when a product is assigned to the specified channel. The corresponding endpoint is Create product channel assignments.
`store/channel/{channel_id}/product/unassigned`	Fires when a product is removed from the specified channel. The corresponding endpoint is 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. The corresponding endpoint is 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. The corresponding endpoint is 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
`store/channel/{channel_id}/settings/route/updated`	Fires on update of any route associated with the specified channel. The corresponding endpoint is 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
`store/channel/{channel_id}/script/created`	Fires on creation of any script associated with the specified channel. The corresponding endpoint is Create a script.
`store/channel/{channel_id}/script/updated`	Fires on update of any script associated with the specified channel. The corresponding endpoint is 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
`store/channel/{channel_id}/settings/*`	Fires when subscribed to all settings updates for the specified channel.
`store/channel/{channel_id}/settings/currency/updated`	Fires when currency associated with the specified channel is updated.
`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. The corresponding endpoint is Update store profile settings.
`store/channel/{channel_id}/settings/locale/added`	Fires when a locale is added to any channel. The corresponding endpoint is Add a locale.
`store/channel/{channel_id}/settings/locale/updated`	Fires when a locale is updated for any channel. The corresponding endpoint is Update a locale.
`store/channel/{channel_id}/settings/locale/deleted`	Fires when a locale is deleted from any channel. The corresponding endpoint is Delete a locale.
`store/channel/{channel_id}/settings/logo/updated`	Fires when any of the global logo settings are updated. The corresponding endpoint is 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.
`store/channel/{channel_id}/settings/favicon/image/updated`	Fires when any of the favicon image settings that apply to the specified channel are updated.
`store/channel/{channel_id}/settings/checkout/updated`	Fires when checkout settings that affect a specified channel are updated. The corresponding endpoint is Update channel cart settings.
`store/channel/{channel_id}/settings/SEO/updated`	Fires when SEO settings that affect the specified channel are updated. The corresponding endpoint is Update storefront SEO settings.
`store/channel/{channel_id}/settings/robots/updated`	Fires when search engine robot settings that affect the specified channel are updated. The corresponding endpoint is Update robots.txt settings.
`store/channel/{channel_id}/settings/category/updated`	Fires when category settings that affect the specified channel are updated. The corresponding endpoint is Update storefront category settings.
`store/channel/{channel_id}/settings/product/updated`	Fires when product settings that affect the specified channel are updated. The corresponding endpoint is Update storefront product settings.
`store/channel/{channel_id}/settings/catalog/updated`	Fires when catalog settings that affect the specified channel are updated. The corresponding endpoint is Update catalog settings.
`store/channel/{channel_id}/settings/security/updated`	Fires when security settings that affect the specified channel are updated. The corresponding endpoint is Update storefront security settings .
`store/channel/{channel_id}/settings/searchContextFilters/updated`	Fires when search context filters that affect the specified channel are updated. The corresponding endpoint is Upsert Contextual Filters.
`store/channel/{channel_id}/settings/defaultCustomerGroup/updated`	Fires when the default customer group associated with the specified channel is updated. The corresponding endpoint is Update a customer group.
`store/channel/{channel_id}/settings/customerPrivacy/updated`	Fires when customer privacy settings that affect the specified channel are updated. The corresponding endpoint is 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
`store/channel/{channel_id}/settings/site/updated`	Fires when a site associated with the specified channel is updated, created, or deleted. The corresponding endpoint is 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. The corresponding endpoint is Upsert a site's checkout URL.
`store/channel/{channel_id}/settings/site/checkoutUrl/deleted`	Fires when checkout domain per channel is deleted. The corresponding endpoint is 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
`store/channel/{channel_id}/socialMediaLinks/updated`	Fires when a social media link associated with the specified channel is updated.

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
`store/channel/{channel_id}/theme/configuration/created`	Fires when a theme associated with the specified channel is created.
`store/channel/{channel_id}/theme/configuration/activated`	Fires when a theme associated with the specified channel is published.

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