eXvisory chatbots gather most information by evaluating Query tests that ask the user questions. A webhook is a new kind of test that adds the powerful capability to ask and answer similar questions by calling out via the Internet to other computer systems.

Webhook settings

At present there is no eXvisory dev user interface for configuring webhooks. To add a webhook download the deep logic network JSON source (Admin> Download > JSON), add the webhook settings as shown below and upload it (Admin> Upload> JSON).

{
  "settings": {
    "version": {
      "major" : 1,
      "minor" : 0,
      "maintenance" : 1,
      "schema" : 2,
      "update" : 214,
      "aiq" : -2.0
    },
    "comments" : [
      "Sample eXvisory deep logic network",
      "Mice in the bed!",
      "Copyright eXvisory.ai 2019. All rights reserved."
    ],
    "webhook": {
      "url" : "https://secret-basin-59856.herokuapp.com/webhook",
      "username" : "wonka",
      "password" : "123456",
      "headers": [
        {"key" : "key1", "value" : "value1"}
      ]
    }
  },
  "faults" : ...

The webhook settings are simple. Provide the URL of a web service you will create that is capable of processing POST requests and add an optional username and password for basic authentication and optional application-specific headers. An eXvisory deep logic network can currently only define a single webhook, but the data it is passed enables you to implement any number of tests.

Using a webhook

To show how to use an eXvisory webhook we have extended our 'mice in the bed' tutorial. Upload the webhook version of the tutorial (below) into your eXvisory dev instance.

You should see a new cat_picture synthetic test that has a special (webhook) expression in its result field. If a webhook has been configured this test will invoke it and return a logic value, just like any other test. Our sample webhook returns the URL of a random cat picture, which is presented to the user via the "result" resource.

It's really as simple as that. The cat_picture webhook test is included in the conditions clause of the cat_facts test, just like any other test.

Webhook handler

You may have hoped the webhook could directly connect to other computer systems but this is impractical given the huge variation in web APIs, data encodings, authentication, etc. So you have to build your own Internet-hosted webhook handler that 'understands' eXvisory webhook requests and translates and connects them to the other computer systems. Fortunately, with modern software frameworks this is very straightforward.

const express = require('express');
const axios = require('axios');
​
const app = express();
​
// Refer to PORT environment variable for Heroku deployment
let port = process.env.PORT;
if (port == null || port == "")
  port = 3000;
​
// Use express.json middleware (to parse JSON body)
app.use(express.json({}));
​
app.post('/webhook', (req, res, next) => {
​
    console.log(req.body);
    console.log('Authorization = ' + req.get('Authorization'));
​
    axios.get('https://api.thecatapi.com/v1/images/search', { timeout : 2000 })
        .then(function(response) {
            res.json({ result: response.data[0].url });
        })
        .catch(function(error) {
            next(error);
        });
​
});
​
app.listen(port, () => console.log(`Example app listening on port ${port}!`));

2019-05-15T13:38:39.785222: { token: 'x_test_cat_picture',
2019-05-15T13:38:39.785235:   facts: 
2019-05-15T13:38:39.785238:    { bed_mice_eliminator: 'UNKNOWN',
2019-05-15T13:38:39.785240:      cat_own: true,
2019-05-15T13:38:39.785241:      cat_own_usr: 'Yes (I have a cat)',
2019-05-15T13:38:39.785243:      cat_eliminator: 'UNKNOWN',
2019-05-15T13:38:39.785245:      exvisory_version: '1.0.1.214',
2019-05-15T13:38:39.785250:      cat_name: 'Hooded Paw',
2019-05-15T13:38:39.785251:      bed_mice_user: 'Martin',
2019-05-15T13:38:39.785253:      exvisory_retries: {},
2019-05-15T13:38:39.785255:      exvisory_origin: 'https://test.exvisory.ai',
2019-05-15T13:38:39.785257:      exvisory_aiq: '-2.0' } }
2019-05-15T13:38:39.785287: Authorization = Basic d29ua2E6MTIzNDU2

Here's our sample webhook handler developed using Node.js and the Express and Axios Javascript frameworks and hosted on Heroku. Even if you're not a Javascript programmer you can see it logs the JSON data sent to it by the eXvisory chatbot (see the 'Logs' tab above), logs any basic authentication header and then calls a web API that returns the URL of a random cat photo. It returns the URL to eXvisory as a string logic variable in a simple JSON object.

If you look at the logs you will see that eXvisory sends the webhook handler a token identifying the calling test (in this case x_test_cat_picture) and all the Facts currently known to the eXvisory deep logic network. Use this data in your webhook handler to return appropriate results.

See our webhook reference for details.