Setting Up your Webhook

Dariusz Zabrzenski
5 min read
updated: May 9, 2022

Create webhooks to provide efficient communication between the bot and your web services.

Setup stepsLink icon

To follow this guide to set up your webhook, all you need is a computer with Node.js installed.

Other Languages
To follow this guide, you will need to install Node.js, but you can write your webhook in whatever server-side language you like.
Other Languages
To follow this guide, you will need to install Node.js, but you can write your webhook in whatever server-side language you like.

Step 1 - Create a new Node.js projectLink icon

Run the following on the command line to create the needed files and dependencies:

mkdir chatbot-webhooks // creates a directory
cd chatbot-webhooks // open created directory
touch index.js // creates empty index.js file
npm init // creates package.json
npm install express body-parser --save // installs using dependencies

Step 2 - Create a HTTP serverLink icon

Add the following code to index.js and put your verification token into token variable.

What is verification token?
Verification should be used to verify if the request comes from a trusted source. It’s optional and can be empty.
What is verification token?
Verification should be used to verify if the request comes from a trusted source. It’s optional and can be empty.
'use strict';

const express = require('express');
const bodyParser = require('body-parser');
const app = express().use(bodyParser.json()); // creates http server
const token = 'VERIFICATION_TOKEN'; // type here your verification token

app.listen(3000, () => console.log('[ChatBot] Webhook is listening'));

This code creates an HTTP server that listens for requests on port 3000. For this guide we are using Express.js, but you can do it using only Node.js or any other framework you love.

Step 3 - Return the challengeLink icon

Add the following code to index.js:

app.get('/', (req, res) => {
    // check if verification token is correct
    if (req.query.token !== token) {
        return res.sendStatus(401);
    }

    // return challenge
    return res.end(req.query.challenge);
});

This code is required to ensure your webhook is authentic and working. In this code, we’re checking that your verification token is correct with the one sent in the request. We’re also returning a challenge response to confirm that your webhook works correctly.

Step 4 - Webhook endpointLink icon

Add the following code to index.js:

app.post('/', (req, res) => {
    // check if verification token is correct
    if (req.query.token !== token) {
        return res.sendStatus(401);
    }

    // print request body
    console.log(req.body);

    // return a text response
    const data = {
        responses: [
            {
                type: 'randomText',
                messages: ['Hi', 'Hello']
            }
        ]
    };

    res.json(data);
});

This code creates your webhook endpoint.

Similarly, as in the previous step, we have to check if your verifying token and the received token are the same. If these tokens are identical, ChatBot returns the object and an example bot response.

Note that the endpoint returns a 200OK response, which tells the ChatBot the event that has been received.

Main steps in the verification process:Link icon

  • To create a verification token, chose a random string and assign its value to the token parameter.
  • Go to your ChatBot dashboard and select Webhooks. Enter the verification token in the appropriate field.
  • ChatBot sends a GET request to your webhook with the verification token in the token parameter of the query string.
  • Verify the received token with the verification token. If both string match, respond with the challenge parameter.
  • Your webhook has been verified successfully.

Step 5 - Publish your webhook serverLink icon

In this tutorial we’re using ngrok which exposes local servers behind NATs and firewalls to the public internet over secure tunnels. For production usage you should deploy your webhook code to the server of your choice. This can be your own hardware or cloud-based service like AWS or Heroku.

Run the following command to start your webhook on the localhost server: node index.js.

  1. Install ngrok to expose the web server, you’ve just created, running on your local machine to the internet. Most people set an alias for ngrok or keep it in their user folder for easy access in the command line.
    On Linux and OSX you can unzip ngrok from a terminal with the following command $ unzip /path/to/ngrok.zip. On Windows, just double click ngrok.zip.
    On Linux and OSX you can unzip ngrok from a terminal with the following command $ unzip /path/to/ngrok.zip. On Windows, just double click ngrok.zip.
  2. In the folder with the created index.js file, run the following command: node index.js
  3. Run ngrok in a new terminal window to listen on the port 3000. ./ngrok http 3000
  4. Now you should see a similar screen the the one below. Note that the address in the Forwarding line states the public address of your webhook. In this case, it is https://4f1aabc7.ngrok.io. Save this address for later.

Step 6 - Set up webhook in ChatBotLink icon

  1. Go to ChatBot app and select integrations from the left panel of your dashboard.
  2. Go to workflow and select webhooks.
  3. Click on Create new webhook button. Now you’re in the webhook view. Give your webhook a name, to quickly identify it and paste its URL. In this example: https://4f1aabc7.ngrok.io.
  4. Enter the verification token chosen in step 2.
  5. Click the save button to keep your changes.

Step 7 - Add the webhook in your StoryLink icon

Step 8 - Test your story with webhooksLink icon

Now your webhook is ready to test. A triggered interaction that has a webhook should send, as the response, the message from your webhook.

Ready to use examplesLink icon

Was this article helpful?

Got it!

Thanks for your feedback.

Thank you!

We’re happy to help.

Start a free ChatBot trial
and build your first chatbot today!

Free 14-day trial No credit card required

Discover our other products