Webhooks Tutorial

In this tutorial, we’ll create a Node.js Express app that handles webhook callbacks and uses ngrok (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 with OAuth scopes that include Information & Settings read-only and Products read-only.
• Webhooks Overview
• 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).

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.

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.

To install ngrok and connect it to your account, follow the ngrok setup steps on the Remote tunnels page. This tutorial uses ngrok’s traffic inspector to observe webhook callbacks, but any remote tunnel works for receiving them.

Start the app

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

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:

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.

Create a webhook

Now, we’ll create a webhook that subscribes to the store/product/updated webhook event. To do so, send a POST request to /stores/{{STORE_HASH}}/v3/hooks.

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
}

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

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.

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.

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’:

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

Getting error “ngrok not found”?

This usually means ngrok is not on your system PATH. See Remote tunnels troubleshooting for how to fix it on macOS, Linux, and Windows.

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?

Resources

• Webhooks Overview
• Webhook Events
• Webhooks Reference