BigCommerce Webhooks v3 is an advanced tool that allows users to automate and streamline their e-commerce operations. By utilizing webhooks, users can set up triggers that automatically notify them of specific events such as new orders, product updates, or customer activity. This real-time data allows users to stay informed and respond quickly to changes in their store.
openapi: 3.0.3
info:
title: BigCommerce Webhooks v3
version: ''
description: >-
Get notified when specific events occur on a BigCommerce store. For more
information, see the [Webhooks Overview](/docs/integrations/webhooks).
termsOfService: https://www.bigcommerce.com/terms
contact:
email: [email protected]
name: BigCommerce
url: https://www.bigcommerce.com
tags:
- name: Manage Webhooks (Bulk)
- name: Manage Webhooks (Single)
- name: Webhook Events
- name: Webhooks Admin
security:
- X-Auth-Token: []
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
variables:
store_hash:
default: store_hash
description: Permanent ID of the BigCommerce store.
description: BigCommerce API Gateway
paths:
/hooks:
post:
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/webhook_Full'
meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
examples:
application/json:
value:
data:
id: 18048287
client_id: m9r6keqmo7h7f23btnpwernbez1kglkl
store_hash: sftg45fsd
created_at: 1561488106
updated_at: 1561488106
scope: store/order/*
destination: https://665b65a6.ngrok.io/webhooks
is_active: true
headers:
custom-key: developer-defined value
meta:
pagination:
count: 5
current_page: 1
links:
current: '?limit=100&page=1'
next: '?limit=100&page=1'
previous: '?limit=100&page=1'
per_page: 100
total: 5
total_pages: 1
links:
getHook:
operationId: getWebhook
parameters:
webhook_id: $response.body#/id
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
summary: BigCommerce Create a Webhook
description: >-
Creates a webhook. Only one webhook at a time can be created. Custom
headers can be added. Destination URL must be served on port 443 (custom
ports are not currently supported).
operationId: createWebhooks
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/webhook_Base'
tags:
- Manage Webhooks (Bulk)
get:
responses:
'200':
$ref: '#/components/responses/webhooks_Resp'
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
summary: BigCommerce Get Webhooks
description: >-
Returns a list of all webhooks on a store associated to the `client_id`
used to authenticate the request.
*Note: BigCommerce determines the `client_id` from the `access_token`.*
operationId: getWebhooks
tags:
- Manage Webhooks (Bulk)
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/FilterPageParam'
- $ref: '#/components/parameters/FilterLimitParam'
- $ref: '#/components/parameters/IsActive'
- $ref: '#/components/parameters/FilterByScope'
- $ref: '#/components/parameters/FilterByDestination'
/hooks/{webhook_id}:
get:
responses:
'200':
$ref: '#/components/responses/webhook_Resp'
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
'404':
$ref: '#/components/responses/404_NotFound'
description: Return a webhook by ID.
operationId: getWebhook
summary: BigCommerce Get a Webhook
tags:
- Manage Webhooks (Single)
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
parameters:
- $ref: '#/components/parameters/WebhookId'
put:
responses:
'200':
$ref: '#/components/responses/webhook_Resp'
summary: BigCommerce Update a Webhook
description: Updates a webhook. Custom headers can be added.
operationId: updateWebhook
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/webhook_Put'
x-examples:
application/json:
scope: store/cart/lineItem/*
destination: https://myapp.herokuapp.com/
is_active: true
headers:
User-Name: Hello
Password: Goodbye
tags:
- Manage Webhooks (Single)
delete:
responses:
'200':
$ref: '#/components/responses/webhook_Resp'
summary: BigCommerce Delete a Webhook
description: >-
Deletes a webhook. Only one webhook at a time can be deleted. When a
webhook is deleted, it is returned in the response as a 200 OK.
operationId: deleteWebhook
tags:
- Manage Webhooks (Single)
parameters:
- $ref: '#/components/parameters/Accept'
- $ref: '#/components/parameters/Content-Type'
/hooks/admin:
get:
operationId: getHooksAdmin
summary: BigCommerce Get Admin Info
description: >-
List all notification emails, webhooks, and denylisted domains
associated with the API account.
parameters:
- $ref: '#/components/parameters/IsActive'
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
emails:
description: Email addresses to be sent notifications.
type: array
items:
type: string
format: email
example: [email protected]
hooks_list:
description: >-
List of all the webhooks associated with the provider
API account, filtered by the `active` parameter.
type: array
items:
type: object
properties:
id:
type: integer
description: ID of the webhook
client_id:
type: string
minLength: 1
description: Client ID, unique to the store or app.
store_hash:
minLength: 1
type: string
description: Permanent ID of the BigCommerce store.
scope:
type: string
minLength: 1
description: Event you subscribe to
example: store/order/*
destination:
type: string
minLength: 1
description: >-
URL must be active, return a 200 response, and
be served on port 443. Custom ports arenʼt
currently supported.
headers:
type: object
description: >-
You can pass in any number of custom headers to
validate webhooks being returned.
properties: {}
nullable: true
additionalProperties:
type: string
is_active:
type: boolean
description: >-
If the webhook is active or not. A webhook
subscription becomes deactivated after 90 days
of inactivity.
default: true
created_at:
type: integer
example: 1561488106
description: >-
The time the webhook was created, represented in
UNIX epoch time.
updated_at:
type: integer
example: 1561488106
description: >-
The time the webhook was most recently updated,
represented in UNIX epoch time.
status:
type: string
description: The webhook status.
enum:
- inactive
- active
- deactivated
blocked_domains:
description: >-
List of domains (destinations) that are currently on
the denylist and are not being sent webhooks.
type: array
items:
type: object
properties:
destination:
description: Domain URL to which webhooks are sent.
type: string
format: url
time_left:
description: >-
Remaining time in seconds that the domain is on
the denylist.
type: integer
reasons:
type: array
items:
type: object
properties:
failure_description:
type: string
count:
type: integer
timestamp:
type: integer
format: int64
description: >-
UTC timestamp in seconds that the events
was created
meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
examples: {}
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
tags:
- Webhooks Admin
put:
operationId: updateHooksAdmin
summary: BigCommerce Upsert Email Notifications
description: >
Update email addresses that are sent notification emails when any domain
associated with the API account is denylisted or when a webhook is
deactivated. Supports `upsert` functionality in the case that no email
address exists yet.
requestBody:
description: List of notification emails.
content:
application/json:
schema:
type: object
properties:
emails:
type: array
items:
type: string
format: email
example: [email protected]
examples:
Example:
value:
emails:
- [email protected]
required: true
responses:
'204':
description: No Content
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
'422':
$ref: '#/components/responses/422_UnprocessableEntity'
tags:
- Webhooks Admin
/hooks/events:
get:
tags:
- Webhook Events
summary: BigCommerce Get Events
deprecated: true
parameters:
- $ref: '#/components/parameters/FilterPageParam'
- $ref: '#/components/parameters/FilterLimitParam'
- $ref: '#/components/parameters/FilterMaxCreatedAtParam'
- $ref: '#/components/parameters/FilterMinCreatedAtParam'
operationId: getWebhookEvents
responses:
'200':
description: Successful operation.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/HistoryEvent'
meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
'400':
$ref: '#/components/responses/400_BadRequest'
'401':
$ref: '#/components/responses/401_Unauthorized'
description: >
Get a list of events that were sent but not successfully received.
Events are stored for not less than one week.
components:
parameters:
WebhookId:
name: webhook_id
in: path
description: The ID of a Webhook.
required: true
schema:
type: integer
minimum: 1
example: 22561593
IsActive:
name: is_active
in: query
description: >
Enables user to filter for webhooks that are active or not. A webhook
subscription becomes deactivated after 90 days of inactivity.
schema:
type: boolean
example: true
FilterByScope:
name: scope
in: query
description: |
Enables user to filter for webhooks by scope.
schema:
type: string
FilterByDestination:
name: destination
in: query
description: |
Enables user to filter for webhooks by destination.
schema:
type: string
FilterPageParam:
name: page
in: query
description: |
Page number.
required: false
schema:
type: integer
example: 1
FilterLimitParam:
name: limit
in: query
description: |
Items count per page.
required: false
schema:
type: integer
FilterMaxCreatedAtParam:
name: created_at:max
in: query
description: |
Maximum value for returned data.
required: false
schema:
type: string
FilterMinCreatedAtParam:
name: created_at:min
in: query
description: |
Minimum value for returned data.
required: false
schema:
type: string
Accept:
in: header
name: Accept
schema:
type: string
default: application/json
Content-Type:
name: Content-Type
in: header
schema:
type: string
default: application/json
responses:
webhooks_Resp:
description: ''
content:
application/json:
schema:
description: ''
type: object
properties:
data:
type: array
uniqueItems: true
minItems: 1
items:
type: object
properties:
id:
type: integer
client_id:
type: string
minLength: 1
store_hash:
type: string
minLength: 1
scope:
type: string
minLength: 1
destination:
type: string
minLength: 1
headers:
type: object
properties: {}
nullable: true
additionalProperties:
type: string
is_active:
type: boolean
created_at:
type: integer
description: >-
The time the webhook was created, represented in UNIX
epoch time.
updated_at:
type: integer
description: >-
The time the webhook was most recently updated,
represented in UNIX epoch time.
meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
examples: {}
502_GatewayError:
description: >-
If something happens during the request that causes it to fail, a 502
response will be returned. A new request should be made; however, it
could fail.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 502
title: >-
A login URL could not be generated. Please try another
request.
type: /api-docs/getting-started/api-status-codes
503_ServiceUnavailable:
description: >-
If this occurs, you should retry the request. If you are unable to
successfully make a request, please check the BigCommerce [system
status](https://status.bigcommerce.com/). A service is likely down and
the request will need to be made again when it is back up (in several
hours usually)
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 503
title: Service Unavailable
type: /api-docs/getting-started/api-status-codes
504_GatewayTimeout:
description: >-
If this occurs, you should retry the request. Typically retrying the
request several times will result in a successful request; However, if
you are unable to successfully make a request, please check the
BigCommerce [system status](https://status.bigcommerce.com/). A service
is likely down and the request will need to be made again when it is
back up (in several hours usually)
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetailed_Full'
examples:
response:
value:
status: 504
title: Gateway Timeout
type: /api-docs/getting-started/api-status-codes
errors: {}
400_BadRequest:
description: >-
Malformed request syntax. Typically need to fix the JSON request body to
resend successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 400
title: Input is invalid.
type: /api-docs/getting-started/api-status-codes
401_Unauthorized:
description: >-
Unauthorized - the v3 Auth client ID or token in the request are not a
valid combination for this store.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 401
title: >-
Unauthorized - the v3 Auth client ID or token in the request
are not a valid combination for this store.
type: /api-docs/getting-started/api-status-codes
403_Unauthorized:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 403
title: >-
Unauthorized Access. You do not have permission to make this
request.
type: /api-docs/getting-started/api-status-codes
404_NotFound:
description: If the requested webhook is not found, return a 404 Not Found.
content:
application/json:
schema:
$ref: '#/components/schemas/error_Full'
examples:
response:
value:
status: 404
title: Webhook with id [{webhook_id}] not found
type: /api-docs/getting-started/api-status-codes
422_UnprocessableEntity:
description: >-
This occurs when missing or unacceptable data is passed for one or more
fields. Please correct the values for the fields listed in the errors
object.
content:
application/json:
schema:
$ref: '#/components/schemas/errorDetailed_Full'
examples:
response:
value:
status: 422
title: JSON data is missing or invalid
type: /api-docs/getting-started/api-status-codes
errors:
destination: error.path.missing.
webhook_Resp:
description: Example response
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
data:
id: 22041448
client_id: hm6ttr1z8fzu2utb7d1p9qile9jtugv
store_hash: 29iql3rwa6
scope: store/order/*
destination: https://665b65a6.ngrok.io/webhooks
headers:
is_active: false
created_at: 1626812212
updated_at: 1627588222
meta: {}
properties:
data:
type: object
properties:
id:
type: integer
client_id:
type: string
minLength: 1
store_hash:
type: string
minLength: 1
scope:
type: string
minLength: 1
destination:
type: string
minLength: 1
headers:
type: object
properties: {}
nullable: true
additionalProperties:
type: string
is_active:
type: boolean
created_at:
type: integer
description: >-
The time the webhook was created, represented in UNIX
epoch time.
updated_at:
type: integer
description: >-
The time the webhook was most recently updated,
represented in UNIX epoch time.
meta:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
examples:
application/json:
value:
data:
id: 18048287
client_id: m9r6keqmo7h7f23btnpwernbez1kglkl
store_hash: sftg45fsd
created_at: 1561488106
updated_at: 1561488106
scope: store/order/*
destination: https://665b65a6.ngrok.io/webhooks
is_active: true
headers:
custom-key: developer-defined value
meta:
pagination:
count: 5
current_page: 1
links:
current: '?limit=100&page=1'
next: '?limit=100&page=1'
previous: '?limit=100&page=1'
per_page: 100
total: 5
total_pages: 1
securitySchemes:
X-Auth-Token:
name: X-Auth-Token
description: >-
### OAuth scopes
None required. Create and manage webhooks with the default scope of an
API account.
### Authentication header
| Header | Argument | Description |
|:-|:|:|
| `X-Auth-Token` | `access_token` | For more about API accounts that
generate `access_token`s, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts). |
### Further reading
For example requests and more information about authenticating
BigCommerce APIs, see [Authentication and Example
Requests](/docs/start/authentication#x-auth-token-header-example-requests).
For more about BigCommerce OAuth scopes, see our [Guide to API
Accounts](/docs/start/authentication/api-accounts#oauth-scopes).
For a list of API status codes, see [API Status
Codes](/docs/start/about/status-codes).
type: apiKey
in: header
schemas:
store_cart_wildcard:
description: |-
Fires for each of the following events:
* `store/cart/created`
* `store/cart/updated`
* `store/cart/deleted`
* `store/cart/couponApplied`
* `store/cart/abandoned`
* `store/cart/converted`
* `store/cart/lineItem`
See individual events for more information.
title: store/cart/*
x-examples: {}
x-internal: false
store_cart_created:
description: >-
This webhook fires on new cart creation when any of the following occur:
* a storefront shopper adds their first product to a cart during a new
session
* an application makes a successful `POST` request to `/carts` using
either the [REST Storefront](/docs/rest-storefront/carts#create-a-cart)
API or the [REST
Management](/docs/rest-management/carts/carts-single#create-a-cart) API
* a storefront makes a successful call to create a cart using the
[GraphQL Storefront
API](/docs/storefront/cart-checkout/guide/graphql-storefront)
Cart creation also fires the `store/cart/updated` webhook.
```json filename="Example callback object" showLineNumbers
{
"created_at": 1561482670,
"store_id": "1025646",
"producer": "stores/{store_hash}",
"scope": "store/cart/created",
"hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528",
"data": {
"type": "cart",
"id": "09346904-4175-44fd-be53-f7e598531b6c"
}
}
```
x-examples: {}
title: store/cart/created
allOf:
- $ref: '#/components/schemas/webhook_callback_base'
- description: >-
A lightweight description of the event that triggered the webhook.
Will vary depending on the event registered.
properties:
data:
type: object
description: >-
A lightweight description of the event that triggered the
webhook.
properties:
type:
type: string
description: can be `cart` or `cart_line_item`
example: cart
enum:
- cart
- cart_line_item
id:
type: string
description: ID of the cart
example: 09346904-4175-44fd-be53-f7e598531b6c
x-tags:
- created
type: object
x-internal: false
store_cart_updated:
title: store/cart/updated
description: >-
Fires when one of the following occurs:
* A cartʼs line items are modified by adding a new item to a cart,
updating an existing itemʼs quantity, or deleting an item.
* A shopper enters or changes their email address during guest checkout.
This includes signing in to a customer account after creating a guest
cart, which associates the accountʼs email address with the cart.
The `store/cart/created` webhook firing also triggers this webhook
because adding a product to an empty cart is considered an update.
Changes to the following fields trigger this event:
* Quantity
* Item Price
```json filename="Example callback object" showLineNumbers
{
"created_at": 1561482670,
"store_id": "1025646",
"producer": "stores/{store_hash}",
"scope": "store/cart/updated",
"hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528",
"data": {
"type": "cart",
"id": "09346904-4175-44fd-be53-f7e598531b6c"
}
}
```
x-examples: {}
allOf:
- $ref: '#/components/schemas/webhook_callback_base'
- description: >-
A lightweight description of the event that triggered the webhook.
Will vary depending on the event registered.
properties:
data:
type: object
description: >-
A lightweight description of the event that triggered the
webhook.
properties:
type:
type: string
description: can be `cart` or `cart_line_item`
example: cart
id:
type: string
description: ID of the cart
example: 09346904-4175-44fd-be53-f7e598531b6c
x-tags:
- created
type: object
x-internal: false
store_cart_deleted:
title: store/cart/deleted
description: >-
Fires when a cart is deleted. Carts are deleted in two ways; when all
items are removed from a cart, and when an API consumer explicitly
removes the cart using a `DELETE` request. Cart deletion ends the cart
lifecycle. The `store/cart/updated` webhook also fires when the last
item is removed.
```json filename="Example callback object" showLineNumbers
{
"created_at": 1561482670,
"store_id": "1025646",
"producer": "stores/{store_hash}",
"scope": "store/cart/deleted",
"hash": "352e4afc6dd3fc85ea26bfdf3f91852604d57528",
"data": {
"type": "cart",
"id": "09346904-4175-44fd-be53-f7e598531b6c"
}
}
```
x-ex
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/webhooks-v3-openapi-original.yml