> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Webhooks Tutorial

In this tutorial, we'll create a Node.js Express app that handles webhook callbacks and uses [ngrok](https://ngrok.com/) (ngrok.com) to expose the app to the Internet. Then, we'll create a webhook and observe the callback using the ngrok web interface when the event is triggered.

### Prerequisites

* A store or app [API account](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts) with [OAuth scopes](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes) that include **Information & Settings** read-only and **Products** read-only.
* [Webhooks Overview](/developer/docs/integrations/webhooks)
* Familiarity with working in the terminal
* Familiarity working with `node` and `npm`

## Create an Express app

First, let's make a `webhooks-test` directory and initialize a Node.js Express app inside of it. To do so, run the following commands in your terminal. These commands work the same across macOS, Linux, and Windows (PowerShell).

```bash showLineNumbers={false}
mkdir webhooks-test         # Create project directory

cd webhooks-test            # Move into project directory

npm init                    # Initialize a Node.js project (hit return to accept the default values)
```

Then, create a file named `index.js` in the project directory and copy and paste the following JavaScript code into it.

```js showLineNumbers={false}
const express = require('express');
const ngrok = require('ngrok')
const app = express();

// when there's a post request to /webhooks...
app.post('/webhooks', function (req, res) {

    // respond with 200 OK
    res.send('OK');
});

// listen to port 3000
app.listen(3000, function () {
    console.log('Listening for webhooks on port 3000');

    // start ngrok and create a tunnel to port 3000
    (async function() {
        const url = await ngrok.connect(3000);
    })();
})
```

This app listens to requests on port `3000`, then responds with a `200` status once it receives a `POST` request to `/webhooks`.

Next, install ngrok so you can expose the app to the Internet.

> **Note**
>
> * Ngrok is a helpful tool for viewing webhook callbacks BigCommerce sends to your app. Ngrok creates a publicly accessible tunnel URL to an application running on your machine. When using ngrok you can view HTTP request details in its web interface.
> * For simplicity, this tutorial uses an [npm package](https://www.npmjs.com/package/ngrok) to run ngrok. For official ngrok usage and installation instructions, visit [ngrok.com](https://ngrok.com/).

Download the installer for your operating system from the [ngrok downloads page](https://ngrok.com/downloads), which provides packages for macOS, Windows, and Linux. If you prefer a package manager, you can use `brew install ngrok/ngrok/ngrok` on macOS or `choco install ngrok` on Windows instead.

Once ngrok is installed, connect it to your account by running the following command, which is the same on every platform:

```bash showLineNumbers={false}
ngrok config add-authtoken <TOKEN>
```

> **Note**
>
> You can obtain your authtoken by going to [https://dashboard.ngrok.com/get-started/your-authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).

## Start the app

First, navigate to your `webhooks-test` project directory and start the Node.js app:

```bash showLineNumbers={false}
node index.js              # Start the app; it listens on port 3000
```

Then, in a second terminal, start ngrok and point it at the app's port:

```bash showLineNumbers={false}
ngrok http 3000            # Expose port 3000 to the Internet
```

Navigate to `http://localhost:4040/` in your browser. You should see the ngrok web interface like shown in the image below. Copy the HTTPS tunnel URL and keep the app running.

![ngrok web interface](/_fern-img/a6cf0171a8909f156c98c2f9028b5dff158f1c20c96da585e14b87d2ea4fe753.webp)

## Create a webhook

Now, we'll create a webhook that subscribes to the `store/product/updated` [webhook event](/developer/docs/integrations/webhooks/event-reference). To do so, send a `POST` request to `/stores/{{STORE_HASH}}/v3/hooks`.

```http showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

{
 "scope": "store/product/updated",
 "destination": "https://6a35e97b.ngrok.io/webhooks", # Replace 6a35e97b.ngrok.io with your HTTPS tunnel URL
 "is_active": true
}
```

> **Note**
>
> * Be sure to replace `6a35e97b.ngrok.io` with your ngrok HTTPS tunnel URL and structure the destination URL as follows: `https://{ngrok_url}/webhooks`.
> * Currently, BigCommerce does not support destination URLs served over custom HTTPS ports. Use the default HTTPS port 443.

## Trigger the webhook event

Webhooks fire when shoppers perform actions on the storefront and when users make changes in the control panel. They will also fire when you make changes using an API. Trigger the webhook you just created by performing the following actions in your BigCommerce control panel:

1. Navigate to **Products** > [**View**](https://login.bigcommerce.com/deep-links/manage/products).
2. Edit a product and change something like **name** or **description**.
3. Click **Save**.

Now, visit the ngrok web interface address (`http://127.0.0.1:4040`) and check for a `200` response.

![ngrok Web Interface](/_fern-img/8882a06bb2edaf82564a43c7b1c6d074373f5be89081b353dea886d4695e6fe2.webp)

The summary shows the webhook fired and our Express app returned a `200` response along with the text OK. The response is generated by `res.send(‘OK')` in our app code. For more information, see [Express Routing](https://expressjs.com/en/guide/routing.html).

> **Note**
>
> Unless you have a paid ngrok account, the destination URL will only be valid for a few hours. After that, the webhook will stop working. Send a `DELETE` request to the specific webhook ID to disable the hook.

## Adding custom headers

You can add custom headers to your create webhook request for added security. The `headers` property accepts any key-value pair as a string. BigCommerce will include the headers in callback requests made to your application.

**`Example request: Add custom headers`**

```http title="Example request: Add custom headers" showLineNumbers={false}
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json
Content-Type: application/json

{
  "scope": "store/cart/lineItem/*",
  "destination": "https://myapp.herokuapp.com/",
  "is_active": true,
  "headers": {
    "Authorization": "Basic SGVsbG86R29vZGJ5ZQ=="
  }
}
```

## Troubleshooting

**Custom ports**

Currently, BigCommerce does not support destination URLs served over custom HTTPS ports. Use the default HTTPS port `443`.

**Getting a `404` error using the root (/) url?**

Add this snippet to your code to respond to incoming `GET` requests with 'hello':

```js showLineNumbers={false}
app.get('/',(req, res)=>{
    res.send('Hello!');
});
```

**Getting error "ngrok not found"?**

This usually means ngrok is not on your system `PATH`. You have two options:

* Add ngrok to your `PATH` so it's available globally from any directory. On macOS and Linux, this typically means moving the binary into a directory already on your `PATH`, for example `mv ngrok /usr/local/bin`. On Windows, add the folder containing `ngrok.exe` to your `PATH` environment variable (see the link below).
* Run ngrok directly from the folder where it lives without changing your `PATH`. On macOS and Linux, use `./ngrok http 3000`; on Windows PowerShell, use `.\ngrok.exe http 3000`.

**Setting the PATH on Windows**

If you are having trouble getting ngrok started on Windows, try setting the `PATH`.

* [What are PATH and other environment variables, and how can I set or use them?](https://superuser.com/questions/284342/what-are-path-and-other-environment-variables-and-how-can-i-set-or-use-them)

## Resources

* [Webhooks Overview](/developer/docs/integrations/webhooks)
* [Webhook Events](/developer/docs/integrations/webhooks/event-reference)
* [Webhooks Reference](/developer/docs/integrations/webhooks)