For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
      • Shipping Provider
      • Tax Provider
      • Webhooks
          • GETList Webhooks
          • POSTCreate Webhook
          • GETGet Webhook
          • PUTUpdate Webhook
          • DELDelete Webhook
          • GETGet Admin Info
          • PUTUpsert Email Notifications
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTIntegrationsWebhooks

Create Webhook

POST
https://api.bigcommerce.com/stores/:store_hash/v3/hooks
POST
/stores/:store_hash/v3/hooks
$curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/hooks \
>     -H "X-Auth-Token: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "scope": "store/order/created",
>  "destination": "https://665b65a6.ngrok.io/webhooks"
>}'
1{
2  "data": {
3    "scope": "store/order/created",
4    "destination": "https://665b65a6.ngrok.io/webhooks",
5    "id": 18048287,
6    "client_id": "m9r6keqmo7h7f23btnpwernbez1kglkl",
7    "store_hash": "sftg45fsd",
8    "created_at": 1561488106,
9    "updated_at": 1561488106,
10    "is_active": true,
11    "headers": {}
12  }
13}

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).

Was this page helpful?
Previous

List Webhooks

Next

Get Webhook

Built with

Authentication

X-Auth-Tokenstring
### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringOptionalDefaults to application/json

Request

This endpoint expects an object.
scopestringRequired
Event you subscribe to.
destinationstringRequired

URL must be active, return a 200 response, and be served on port 443. Custom ports arenʼt currently supported.

is_activebooleanOptional
Boolean value that indicates whether the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity.
headersobject or nullOptional
Headers used to validate that webhooks are active. You can pass in any number of custom headers to validate webhooks are being returned.

Response

dataobject
metaany

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error

OAuth scopes

None required. Create and manage webhooks with the default scope of an API account.

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.