DEVDOCS-6557 - Webhooks for B2B Events (Phase 1)

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:
+<Callout type="important">
+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.
+</Callout>
+
+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)  

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)

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
+}
+```
+
+<Callout type="info">
+
+  * 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.
+</Callout>
+
+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-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: <br />- Company name <br />- Email address <br />- Phone number <br />- Assigned customer group ID (Must be using [Independent Companies](https://support.bigcommerce.com/s/article/Companies-and-Customer-Groups) behavior) <br />- Legal address <br />- UUID <br />- Activity status<br />- Parent Company (Must be using [Account Hierarchy](https://support.bigcommerce.com/s/article/B2B-Edition-Account-Hierarchy)) <br />- Assigned price list (Must be using Dependent Companies behavior) <br />- 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. |
+
+```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: <br />- User name <br />- Email address <br />- Phone number <br />- Assigned customer group ID <br />- Company user extra field values <br />- 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/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: <br />- Email address <br />- Name <br />- Phone number <br />- 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)