Setting Up your Webhook
ChatBot.com ChatBot.com

luiza jurczyk

dariusz zabrzenski

Last update:

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

Setup steps

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.

  1. Create a new Node.js project

    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
  2. Create a HTTP server

    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.

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

  3. Return the challenge

    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.

  4. Webhook endpoint

    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: 'text', elements: ['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:

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

    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.

    1. Run the following command to start your webhook on the localhost server: node index.js.
    2. 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.

    3. In the folder with the created index.js file, run the following command: node index.js
    4. Run ngrok in a new terminal window to listen on the port 3000. ./ngrok http 3000
    5. 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.
  6. Set up webhook in ChatBot

    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.
    4. 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.
    5. Enter the verification token chosen in step 2.
    6. Click the save button to keep your changes.
  7. Connect interaction with created webhook

    1. Go to the interaction you want to connect your webhook with and select the bot responses section.
    2. Select your webhook. You can identify it by it’s name.
    3. Click on the save button to keep your changes.
  8. Test your story with webhooks

    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 examples

Go to next article arrow_forward