Docs
Integrations
Webhooks
Event reference
Channel events

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 / ScopeDescriptionCorresponding Endpoint
store/channel/*Subscribes to all store/channel eventsnot applicable
store/channel/createdFires when a channel is created using the control panel or the APICreate a channel
store/channel/updatedFires when a channel is updated using the control panel or the APIUpdate 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/cart/*Fires on all cart changes associated with the specified channel.not applicable
store/channel/{channel_id}/cart/createdFires on creation of a new cart associated with the specified channel.Create a cart
store/channel/{channel_id}/cart/updatedFires on update of a cart associated with the specified channel.not applicable
store/channel/{channel_id}/cart/deletedFires on deletion of a cart associated with the specified channel.Delete a cart
store/channel/{channel_id}/cart/couponAppliedFires when a new coupon code associated with the specified channel is applied to a cart.not applicable
store/channel/{channel_id}/cart/abandonedFires when a cart associated with the specified channel is abandoned.not applicable
store/channel/{channel_id}/cart/convertedFires 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 / ScopeDescriptionCorresponding 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/createdFires when a new item is added to a cart associated with the specified channel.Add cart line items
store/channel/{channel_id}/cart/lineItem/updatedFires 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/deletedFires 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"
}

Categories

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

Name / ScopeDescriptionCorresponding 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/createdFires on creation of a new category in the category tree that is assigned to the specified channel.Create categories
store/channel/{channel_id}/category/updatedFires on update of a category within the category tree that is assigned to the specified channel.Update categories
store/channel/{channel_id}/category/deletedFires when a category is removed from the category tree that is assigned to the specified channel.Delete categories

Categories payload objects take the form that follows:

Example categories payload object
{
 "store_id": "11111",
 "producer": "stores/abcde",
 "created_at": 1641641646,
 "scope": "store/channel/1/category/created",
 "data": {
    "category_id": 35, // ID of the category
    "tree_id": 1 // ID of the catalog/category tree
  },
 "hash": "3f9ea420af83450d7ef9f78b08c8af25b2213637"
}

Category trees

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

Name / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/categoryTree/updatedFires 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 / ScopeDescriptionCorresponding Endpoint
store/customer/channel/login/access/updatedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/settings/emailStatus/updatedFires when an email status is updated per a specified channel.Update transactional email settings
store/channel/{channel_id}/settings/emailStatus/deletedFires when an email status was deleted per a specified channel.Update transactional email settings
store/channel/{channel_id}/email/templates/updatedFires when an email template is updated per a specified channel.Update a template
store/channel/{channel_id}/email/templates/deletedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/metafield/created/Fires when a channel metafield is created on any channel.Create a channel metafield
store/channel/metafield/updatedFires when any channel metafield is updated.Update a channel metafield
store/channel/metafield/deletedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/notifications/abandonedCart/updatedFires when an abandoned cart notification is updated in the specified channel.Update channel abandoned cart settings
store/channel/{channel_id}/notifications/inventory/updatedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/order/*Fires on all order events associated with the specified channel.not applicable
store/channel/{channel_id}/order/createdFires when an order associated with the specified channel is created.Create an order
store/channel/{channel_id}/order/updatedFires when an order associated with the specified channel is updated.Update an order
store/channel/{channel_id}/order/archivedFires when an order associated with the specified channel is archived.Archive an order
store/channel/{channel_id}/order/statusUpdatedFires when the status of an order associated with the specified channel is updated.not applicable
store/channel/{channel_id}/order/message/createdFires when an order message for an order associated with the specified channel is created using the control panel or the APInot applicable
store/channel/{channel_id}/order/refund/createdFires when a refund is created for all or part of an order associated with the specified channelnot 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/page/createdFires on creation of a page associated with the specified channel.Create pages
store/channel/{channel_id}/page/updatedFires 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 / ScopeDescriptionCorresponding Endpoint
store/priceList/assignment/updatedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/product/assignedFires when a product is assigned to the specified channel.Create product channel assignments
store/channel/{channel_id}/product/unassignedFires when a product is removed from the specified channel.Delete product channel assignments
store/channel/{channel_id}/category/product/assignedFires 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/unassignedFires 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 / ScopeDescriptionCorresponding Endpoint
store/channel/{channel_id}/settings/route/updatedFires 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 / ScopeDescriptionCorresponding Endpoints
store/channel/{channel_id}/script/createdFires on creation of any script associated with the specified channel.Create a script
store/channel/{channel_id}/script/updatedFires 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 / ScopeDescriptionCorresponding 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/updatedFires when currency associated with the specified channel is updated.not applicable
store/channel/{channel_id}/settings/profile/updatedFires 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/updatedFires when any of the global logo settings are updated.Update store logo settings
store/channel/{channel_id}/settings/logo/image/updatedFires when any of the logo image settings that apply to the specified channel are updated.not applicable
store/channel/{channel_id}/settings/favicon/image/updatedFires when any of the favicon image settings that apply to the specified channel are updated.not applicable
store/channel/{channel_id}/settings/checkout/updatedFires when checkout settings that affect a specified channel are updated.Update channel cart settings
store/channel/{channel_id}/settings/SEO/updatedFires when SEO settings that affect the specified channel are updated.Update storefront SEO settings
store/channel/{channel_id}/settings/robots/updatedFires when search engine robot settings that affect the specified channel are updated.Update robots.txt settings
store/channel/{channel_id}/settings/category/updatedFires when category settings that affect the specified channel are updated.Update storefront category settings
store/channel/{channel_id}/settings/product/updatedFires when product settings that affect the specified channel are updated.Update storefront product settings
store/channel/{channel_id}/settings/catalog/updatedFires when catalog settings that affect the specified channel are updated.Update catalog settings
store/channel/{channel_id}/settings/security/updatedFires when security settings that affect the specified channel are updated.Update storefront security settings
store/channel/{channel_id}/settings/searchContextFilters/updatedFires when search context filters that affect the specified channel are updated.Upsert Contextual Filters
store/channel/{channel_id}/settings/defaultCustomerGroup/updatedFires when the default customer group associated with the specified channel is updated.Update a customer group
store/channel/{channel_id}/settings/customerPrivacy/updatedFires 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 / ScopeDescriptionCorresponding Endpoints
store/channel/{channel_id}/settings/site/updatedFires 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/updatedFires when checkout domain per channel is updated.Upsert a site's checkout URL
store/channel/{channel_id}/settings/site/checkoutUrl/deletedFires 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 / ScopeDescriptionCorresponding Endpoints
store/channel/{channel_id}/socialMediaLinks/updatedFires 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 / ScopeDescriptionCorresponding Endpoints
store/channel/{channel_id}/theme/configuration/createdFires when a theme associated with the specified channel is created.Not applicable
store/channel/{channel_id}/theme/configuration/activatedFires 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

Related articles

Did you find what you were looking for?