From 155fa70e419e225cce2d6333d73dc140c1e84e6f Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Tue, 2 Dec 2025 12:11:51 -0600 Subject: [PATCH 1/7] DEVDOCS-6557 - Webhooks for B2B Events (Phase 1) Creating a new article for B2B Edition webhook events and updating releated B2B documentation to call out webhook support. --- docs/b2b-edition/about/index.mdx | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/b2b-edition/about/index.mdx b/docs/b2b-edition/about/index.mdx index 45baec833..041fde96d 100644 --- a/docs/b2b-edition/about/index.mdx +++ b/docs/b2b-edition/about/index.mdx @@ -57,7 +57,15 @@ The V2 API is deprecated, and it does not support many of B2B Edition's newer fe ## API authentication and context -Requests to the B2B Edition REST Management V3 API are always in the context of the server. To authenticate V3 API requests, generate a server to server authToken via one of the following methods: + +As of September 30, 2025, the B2B Edition API `authToken` is deprecated and replaced by the standard BigCommerce API `X-Auth-Token` used together with a new header `X-Store-Hash`. This change only applies to Server-to-Server requests. Storefront requests remain unchanged. + +While `authToken` authentication is not expected to be fully sunset in the near future, it is advised to migrate to the new system as soon as possible to prevent disruption of functionality. + +The server and path for B2B REST Management API endpoints remains the same. + + +Requests to the B2B Edition REST Management V3 API are always in the context of the server. To authenticate V3 API requests, create a BigCommerce API authentication token in the control panel with the B2B Edition scope enabled. Alternatively, you can generate a B2B Edition-only server to server authToken via one of the following methods: * Create an API account from [B2B Edition's settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings) * Generate a token via the [Create a Server to Server Token](/b2b-edition/apis/rest-management/authentication#get-a-server-to-server-token) endpoint @@ -260,6 +268,12 @@ Storefront GraphQL responses contain all the fields specified in the original qu } ``` +## Webhooks + +You can use a store-level or app-level API account to [register and subscribe](/docs/webhooks/webhooks/manage-webhooks-single) to B2B Edition webhook events. Webhooks a resource-efficient alternative to polling the API for keeping your app up-to-date. + +See [B2B Edition Events](/docs/integrations/webhooks/events/b2b-edition) for a complete list of supported webhook events. + ## Resources * [About BigCommerce APIs](/docs/start/about) From d1e8ad4b7a640a1fc6e228115a84099cf5a2d7c2 Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Tue, 2 Dec 2025 12:44:51 -0600 Subject: [PATCH 2/7] DEVDOCS-6557 - Webhooks for B2B Events (Phase 1) Added documentation for B2B Edition webhooks, including creation, callback structure, and event types. --- .../webhooks/events/b2b-edition.mdx | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/integrations/webhooks/events/b2b-edition.mdx diff --git a/docs/integrations/webhooks/events/b2b-edition.mdx b/docs/integrations/webhooks/events/b2b-edition.mdx new file mode 100644 index 000000000..f3e24f9fa --- /dev/null +++ b/docs/integrations/webhooks/events/b2b-edition.mdx @@ -0,0 +1,149 @@ +--- +title: B2B Edition Webhooks +keywords: webhooks, b2b, b2b edition, company, super admin, address, company user, +--- + +# B2B Edition Webhooks + +B2B Edition is BigCommerce’s all-in-one solution that offers enterprise-level B2B functionality to businesses of all types and sizes. It enables business owners to facilitate their B2B operations online and to provide customers with self-service account capabilities and seamless transactions. + +This page is a reference for B2B Edition webhooks and it assumes that you're familiar with webhooks. For a general introduction to webhooks, see [Webhooks Overview](/docs/integrations/webhooks). + +**Note:** B2B Edition currently does not support storefront channel-specific webhooks. + +## Creating a webhook + +To create a webhook, send a request to the [Create a webhook](/docs/webhooks/webhooks/manage-webhooks-bulk#create-a-webhook) endpoint. You must use a BigCommerce store- or app-level API account to authenticate the request; it does not support the API tokens created in your [B2B Edition API Account settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings). Your API account must have the **B2B Edition** scope set to *modify*. + +The following example creates a webhook that subscribes to changes to Company accounts. + +```http filename="Example request: Create a webhook" showLineNumbers copy +POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks +X-Auth-Token: {{ACCESS_TOKEN}} +Content-Type: application/json +Accept: application/json + +{ + "scope": "store/company/*", // The `*` indicates that you subscribe to all Company events + "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](/docs/integrations/webhooks#creating-a-webhook). + +## Callback structure + +For information on webhook callback payload properties, see [Webhook Events](/docs/integrations/webhooks/events#callback-structure). + +## Companies + +The following webhooks fire in response to changes to Company account records. You can use them to track new Company account requests across your storefront channels, updates to Company information, or changes in a Company's activity status. + +| Name / Scope | Description | +|:------------------------|:------------| +| store/company/* | Fires for all store/company events. This includes [Company User](#company-users) and [Company Address](#company-address) events. | +| store/company/created | Fires when a new Company account is created in the storefront, from the B2B Edition control panel, or via the API. Note that this webhook does not fire when the REST Management [Bulk Create Companies](/b2b-edition/apis/rest-management/company/companies#bulk-create-companies) endpoint is used. | +| store/company/updated | Fires when a Company’s basic information is updated, including:
- Company name
- Email address
- Phone number
- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior)
- Legal address
- UUID
- Activity status
- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy))
- Assigned price list (Must be using Dependent Companies behavior)
- Company xtra field values | +| store/company/deleted | Fires when a Company account is deleted from the B2B Edition control panel or via the API. | +| store/company/statusUpdated | Fires when a Company's activity status changes, such as when a pending Company account is approved. | + +```json filename="Example Company created payload object" showLineNumbers copy +{ + "scope": "store/company/created", + "store_id": "123456", + "data": { + "company_id": 1234 + }, + "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", + "created_at": 1561482670, + "producer": "stores/{store_hash}" +} +``` + +## Company Users + +The following webhooks fire in response to changes to Company users. These are B2B customers with a Buyer Portal account connected to a Company. Changes to B2C customers, guest shoppers, and Super Admins do not trigger these webhooks. + +| Name / Scope | Description | +|:------------------------|:------------| +| store/company/user/* | Fires for all store/company/user events. | +| store/company/user/created | Fires when a new Company user is created in the storefront, from the B2B Edition control panel, or via the API. | +| store/company/user/updated | Fires when a Company user's account information is updated, including:
- User name
- Email address
- Phone number
- Assigned customer group ID
- Company user extra field values
- Assigned Company account | +| store/company/user/deleted | Fires when a Company user is deleted in the storefront, from the B2B Edition control panel, or via the API. | + +```json filename="Example Company user created payload object" showLineNumbers copy +{ + "scope": "store/company/user/created", + "store_id": "123456", + "data": { + "company_user_id": 1234 + }, + "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", + "created_at": 1561482670, + "producer": "stores/{store_hash}" +} +``` + +## Company Addresses + +The following webhooks fire in response to changes to addresses saved to Company accounts. Changes to addresses on B2C customer accounts use [Customers webhooks](https://developer.bigcommerce.com/docs/integrations/webhooks/events#customers) instead. + +| Name / Scope | Description | +|:------------------------|:------------| +| store/company/address/* | Fires for all store/company/address events. | +| store/company/address/created | Fires when a new Company address is saved to a Company in the storefront, from the B2B Edition control panel, or via the API. | +| store/company/address/updated | Fires when any field on an existing Company address is updated, including Company address extra field values. | +| store/company/address/deleted | Fires when a Company address is deleted in the storefront, from the B2B Edition control panel, or via the API. | + +```json filename="Example Company address created payload object" showLineNumbers copy +{ + "scope": "store/company/address/created", + "store_id": "123456", + "data": { + "company_address_id": 1234 + }, + "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", + "created_at": 1561482670, + "producer": "stores/{store_hash}" +} +``` + +## Super Admins + +The following webhooks fire in response to changes to [Super Admins](https://developer.bigcommerce.com/b2b-edition/apis/rest-storefront/sales-rep), sales staff who assist Company users from the Buyer Portal. + +| Name / Scope | Description | +|:------------------------|:------------| +| store/superadmin/* | Fires for all store/superadminevents. | +| store/superadmin/created | Fires when a new Super Admin is created the B2B Edition control panel or via the API. | +| store/superadmin/updated | Fires when a Super Admin's account information is updated, including:
- Email address
- Name
- Phone number
- Assigned Company accounts | +| store/superadmin/deleted | Fires when a Super Admin is deleted from the B2B Edition control panel or via the API. | + +```json filename="Example Company address created payload object" showLineNumbers copy +{ + "scope": "store/superadmin/created", + "store_id": "123456", + "data": { + "super-admin_id": 1234 + }, + "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", + "created_at": 1561482670, + "producer": "stores/{store_hash}" +} +``` + +## Resources + +### Related Articles + +* [Webhooks Overview](https://developer.bigcommerce.com/docs/integrations/webhooks) +* [Webhook Events](https://developer.bigcommerce.com/docs/integrations/webhooks/events) +* [Webhooks Reference](https://developer.bigcommerce.com/docs/webhooks/webhooks) +* [B2B Edition Reference](https://developer.bigcommerce.com/b2b-edition/apis) From edc84c191bac3445c488d0acad4e7508beb4df17 Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Tue, 2 Dec 2025 13:12:15 -0600 Subject: [PATCH 3/7] Apply suggestions from code review --- docs/integrations/webhooks/events/b2b-edition.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/integrations/webhooks/events/b2b-edition.mdx b/docs/integrations/webhooks/events/b2b-edition.mdx index f3e24f9fa..2c8991155 100644 --- a/docs/integrations/webhooks/events/b2b-edition.mdx +++ b/docs/integrations/webhooks/events/b2b-edition.mdx @@ -48,9 +48,9 @@ The following webhooks fire in response to changes to Company account records. Y | Name / Scope | Description | |:------------------------|:------------| -| store/company/* | Fires for all store/company events. This includes [Company User](#company-users) and [Company Address](#company-address) events. | +| store/company/* | Fires for all store/company events. This includes [Company User](#company-users) and [Company Address](#company-addresses) events. | | store/company/created | Fires when a new Company account is created in the storefront, from the B2B Edition control panel, or via the API. Note that this webhook does not fire when the REST Management [Bulk Create Companies](/b2b-edition/apis/rest-management/company/companies#bulk-create-companies) endpoint is used. | -| store/company/updated | Fires when a Company’s basic information is updated, including:
- Company name
- Email address
- Phone number
- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior)
- Legal address
- UUID
- Activity status
- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy))
- Assigned price list (Must be using Dependent Companies behavior)
- Company xtra field values | +| store/company/updated | Fires when a Company’s basic information is updated, including:
- Company name
- Email address
- Phone number
- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior)
- Legal address
- UUID
- Activity status
- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy))
- Assigned price list (Must be using Dependent Companies behavior)
- Company extra field values | | store/company/deleted | Fires when a Company account is deleted from the B2B Edition control panel or via the API. | | store/company/statusUpdated | Fires when a Company's activity status changes, such as when a pending Company account is approved. | @@ -121,7 +121,7 @@ The following webhooks fire in response to changes to [Super Admins](https://dev | Name / Scope | Description | |:------------------------|:------------| -| store/superadmin/* | Fires for all store/superadminevents. | +| store/superadmin/* | Fires for all store/superadmin events. | | store/superadmin/created | Fires when a new Super Admin is created the B2B Edition control panel or via the API. | | store/superadmin/updated | Fires when a Super Admin's account information is updated, including:
- Email address
- Name
- Phone number
- Assigned Company accounts | | store/superadmin/deleted | Fires when a Super Admin is deleted from the B2B Edition control panel or via the API. | From 0b6568c4a72ef587b2ed7a7a1176a1ceaaf3731d Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Mon, 8 Dec 2025 15:23:34 -0600 Subject: [PATCH 4/7] DEVDOCS-6557 - Webhooks for B2B Events (Phase 1) Added FAQ about webhooks, and added webhook events page to resources. --- docs/b2b-edition/graphql/overview.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/b2b-edition/graphql/overview.mdx b/docs/b2b-edition/graphql/overview.mdx index f07b64e10..0f54b7a52 100644 --- a/docs/b2b-edition/graphql/overview.mdx +++ b/docs/b2b-edition/graphql/overview.mdx @@ -213,9 +213,14 @@ Use the [open source repository](https://github.com/bigcommerce/b2b-buyer-portal See [GraphQL HTTP status codes for](/docs/start/about/status-codes#graphql-http-status-codes) a list of error messages and explanations. +**Can I create webhooks to notify me when certain B2B Edition events occur?** + +Yes, you can create webhooks to receive basic information on requests made with B2B Edition's GraphQL Storefront APIs. See [B2B Edition Webhooks](/docs/integrations/webhooks/events/b2b-edition.mdx) for a full list of supported events. + ## Resources * [About Our APIs](/b2b-edition/docs/about) * [BigCommerce GraphQL Storefront API overview](/docs/storefront/graphql#pagination) * [Authentication for hosted storefronts](/b2b-edition/docs/authentication#storefront-tokens) +* [B2B Edition Webhooks](/docs/integrations/webhooks/events/b2b-edition.mdx) * [B2B Edition GraphQL Playground](https://api-b2b.bigcommerce.com/graphql/playground) From f1ebce7536bb3786192c3220d48ab2bd3b8ff137 Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Mon, 15 Dec 2025 18:30:34 -0600 Subject: [PATCH 5/7] Apply suggestions from SME review --- .../webhooks/events/b2b-edition.mdx | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/docs/integrations/webhooks/events/b2b-edition.mdx b/docs/integrations/webhooks/events/b2b-edition.mdx index 2c8991155..0eddb4ecc 100644 --- a/docs/integrations/webhooks/events/b2b-edition.mdx +++ b/docs/integrations/webhooks/events/b2b-edition.mdx @@ -15,7 +15,7 @@ This page is a reference for B2B Edition webhooks and it assumes that you're fam To create a webhook, send a request to the [Create a webhook](/docs/webhooks/webhooks/manage-webhooks-bulk#create-a-webhook) endpoint. You must use a BigCommerce store- or app-level API account to authenticate the request; it does not support the API tokens created in your [B2B Edition API Account settings](https://support.bigcommerce.com/s/article/B2B-Edition-Settings). Your API account must have the **B2B Edition** scope set to *modify*. -The following example creates a webhook that subscribes to changes to Company accounts. +The following example creates a webhook that subscribes to creation events for Company accounts. ```http filename="Example request: Create a webhook" showLineNumbers copy POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks @@ -24,7 +24,7 @@ Content-Type: application/json Accept: application/json { - "scope": "store/company/*", // The `*` indicates that you subscribe to all Company events + "scope": "store/company/created", "destination": "https://placeholder.ngrok.io/webhooks", // replace placeholder.ngrok.io with your HTTPS tunnel URL "is_active": true } @@ -48,7 +48,6 @@ The following webhooks fire in response to changes to Company account records. Y | Name / Scope | Description | |:------------------------|:------------| -| store/company/* | Fires for all store/company events. This includes [Company User](#company-users) and [Company Address](#company-addresses) events. | | store/company/created | Fires when a new Company account is created in the storefront, from the B2B Edition control panel, or via the API. Note that this webhook does not fire when the REST Management [Bulk Create Companies](/b2b-edition/apis/rest-management/company/companies#bulk-create-companies) endpoint is used. | | store/company/updated | Fires when a Company’s basic information is updated, including:
- Company name
- Email address
- Phone number
- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior)
- Legal address
- UUID
- Activity status
- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy))
- Assigned price list (Must be using Dependent Companies behavior)
- Company extra field values | | store/company/deleted | Fires when a Company account is deleted from the B2B Edition control panel or via the API. | @@ -73,9 +72,8 @@ The following webhooks fire in response to changes to Company users. These are B | Name / Scope | Description | |:------------------------|:------------| -| store/company/user/* | Fires for all store/company/user events. | | store/company/user/created | Fires when a new Company user is created in the storefront, from the B2B Edition control panel, or via the API. | -| store/company/user/updated | Fires when a Company user's account information is updated, including:
- User name
- Email address
- Phone number
- Assigned customer group ID
- Company user extra field values
- Assigned Company account | +| store/company/user/updated | Fires when a Company user's account information is updated, including:
- User name
- Email address
- Phone number
- Company user extra field values | | store/company/user/deleted | Fires when a Company user is deleted in the storefront, from the B2B Edition control panel, or via the API. | ```json filename="Example Company user created payload object" showLineNumbers copy @@ -97,7 +95,6 @@ The following webhooks fire in response to changes to addresses saved to Company | Name / Scope | Description | |:------------------------|:------------| -| store/company/address/* | Fires for all store/company/address events. | | store/company/address/created | Fires when a new Company address is saved to a Company in the storefront, from the B2B Edition control panel, or via the API. | | store/company/address/updated | Fires when any field on an existing Company address is updated, including Company address extra field values. | | store/company/address/deleted | Fires when a Company address is deleted in the storefront, from the B2B Edition control panel, or via the API. | @@ -107,7 +104,8 @@ The following webhooks fire in response to changes to addresses saved to Company "scope": "store/company/address/created", "store_id": "123456", "data": { - "company_address_id": 1234 + "company_id": 123456, + "address_id": 1234 }, "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", "created_at": 1561482670, @@ -121,9 +119,8 @@ The following webhooks fire in response to changes to [Super Admins](https://dev | Name / Scope | Description | |:------------------------|:------------| -| store/superadmin/* | Fires for all store/superadmin events. | | store/superadmin/created | Fires when a new Super Admin is created the B2B Edition control panel or via the API. | -| store/superadmin/updated | Fires when a Super Admin's account information is updated, including:
- Email address
- Name
- Phone number
- Assigned Company accounts | +| store/superadmin/updated | Fires when a Super Admin's account information is updated, including:
- Email address
- Name
- Phone number
- Assigned/Unassigned Company accounts | | store/superadmin/deleted | Fires when a Super Admin is deleted from the B2B Edition control panel or via the API. | ```json filename="Example Company address created payload object" showLineNumbers copy @@ -131,7 +128,7 @@ The following webhooks fire in response to changes to [Super Admins](https://dev "scope": "store/superadmin/created", "store_id": "123456", "data": { - "super-admin_id": 1234 + "user_id": 1234 }, "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", "created_at": 1561482670, From ff9ace46a9159c42e46b479dc7908c8b1a7370bf Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Mon, 15 Dec 2025 18:31:05 -0600 Subject: [PATCH 6/7] Apply suggestions from code review --- docs/integrations/webhooks/events/b2b-edition.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/integrations/webhooks/events/b2b-edition.mdx b/docs/integrations/webhooks/events/b2b-edition.mdx index 0eddb4ecc..9c2fed1b0 100644 --- a/docs/integrations/webhooks/events/b2b-edition.mdx +++ b/docs/integrations/webhooks/events/b2b-edition.mdx @@ -81,7 +81,8 @@ The following webhooks fire in response to changes to Company users. These are B "scope": "store/company/user/created", "store_id": "123456", "data": { - "company_user_id": 1234 + "company_id": 123456, + "user_id": 321 }, "hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528", "created_at": 1561482670, From a1c0ed92d61e1fcbee15b48a4ba7d3074675a642 Mon Sep 17 00:00:00 2001 From: bc-Vince <97260137+bc-Vince@users.noreply.github.com> Date: Mon, 15 Dec 2025 18:44:06 -0600 Subject: [PATCH 7/7] Update docs/integrations/webhooks/events/b2b-edition.mdx --- docs/integrations/webhooks/events/b2b-edition.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/integrations/webhooks/events/b2b-edition.mdx b/docs/integrations/webhooks/events/b2b-edition.mdx index 9c2fed1b0..7a37739c6 100644 --- a/docs/integrations/webhooks/events/b2b-edition.mdx +++ b/docs/integrations/webhooks/events/b2b-edition.mdx @@ -48,7 +48,7 @@ The following webhooks fire in response to changes to Company account records. Y | Name / Scope | Description | |:------------------------|:------------| -| store/company/created | Fires when a new Company account is created in the storefront, from the B2B Edition control panel, or via the API. Note that this webhook does not fire when the REST Management [Bulk Create Companies](/b2b-edition/apis/rest-management/company/companies#bulk-create-companies) endpoint is used. | +| store/company/created | Fires when a new Company account is created in the storefront, from the B2B Edition control panel, or via the Server to Server API. Note that this webhook does not fire when the REST Management [Bulk Create Companies](/b2b-edition/apis/rest-management/company/companies#bulk-create-companies) endpoint is used. | | store/company/updated | Fires when a Company’s basic information is updated, including:
- Company name
- Email address
- Phone number
- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior)
- Legal address
- UUID
- Activity status
- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy))
- Assigned price list (Must be using Dependent Companies behavior)
- Company extra field values | | store/company/deleted | Fires when a Company account is deleted from the B2B Edition control panel or via the API. | | store/company/statusUpdated | Fires when a Company's activity status changes, such as when a pending Company account is approved. |