(NEW) Webhook
The eXvisory webhook API may be subject to changes that break deep logic networks that use them (as we learn more about webhook usage) so please let us know if you are using them and look out for webhook-related product updates.
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).
Do not edit the version settings and check that the schema version is 2 or greater. If the schema version is 1 use eXvisory dev to make a change to your deep logic network and save it to update the schema version.
1
{
2
"settings": {
3
"version": {
4
"major" : 1,
5
"minor" : 0,
6
"maintenance" : 1,
7
"schema" : 2,
8
"update" : 214,
9
"aiq" : -2.0
10
},
11
"comments" : [
12
"Sample eXvisory deep logic network",
13
"Mice in the bed!",
14
"Copyright eXvisory.ai 2019. All rights reserved."
15
],
16
"webhook": {
17
"url" : "https://secret-basin-59856.herokuapp.com/webhook",
18
"username" : "wonka",
19
"password" : "123456",
20
"headers": [
21
{"key" : "key1", "value" : "value1"}
22
]
23
}
24
},
25
"faults" : ...
Copied!
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.
Work through the tutorial to learn how to backup, download and upload JSON sources from/to your eXvisory dev instance.
bed-mice-w.json
17KB
Code
Webhook version of the 'mice in the bed' deep logic network
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.
cat_picture webhook test
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.
cat_facts synthetic 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.
Webhook handler
Logs
1
const express = require('express');
2
const axios = require('axios');
3
​
4
const app = express();
5
​
6
// Refer to PORT environment variable for Heroku deployment
7
let port = process.env.PORT;
8
if (port == null || port == "")
9
port = 3000;
10
​
11
// Use express.json middleware (to parse JSON body)
12
app.use(express.json({}));
13
​
14
app.post('/webhook', (req, res, next) => {
15
​
16
console.log(req.body);
17
console.log('Authorization = ' + req.get('Authorization'));
18
​
19
axios.get('https://api.thecatapi.com/v1/images/search', { timeout : 2000 })
20
.then(function(response) {
21
res.json({ result: response.data[0].url });
22
})
23
.catch(function(error) {
24
next(error);
25
});
26
​
27
});
28
​
29
app.listen(port, () => console.log(`Example app listening on port ${port}!`));
Copied!
1
2019-05-15T13:38:39.785222: { token: 'x_test_cat_picture',
2
2019-05-15T13:38:39.785235: facts:
3
2019-05-15T13:38:39.785238: { bed_mice_eliminator: 'UNKNOWN',
4
2019-05-15T13:38:39.785240: cat_own: true,
5
2019-05-15T13:38:39.785241: cat_own_usr: 'Yes (I have a cat)',
6
2019-05-15T13:38:39.785243: cat_eliminator: 'UNKNOWN',
7
2019-05-15T13:38:39.785245: exvisory_version: '1.0.1.214',
8
2019-05-15T13:38:39.785250: cat_name: 'Hooded Paw',
9
2019-05-15T13:38:39.785251: bed_mice_user: 'Martin',
10
2019-05-15T13:38:39.785253: exvisory_retries: {},
11
2019-05-15T13:38:39.785255: exvisory_origin: 'https://test.exvisory.ai',
12
2019-05-15T13:38:39.785257: exvisory_aiq: '-2.0' } }
13
2019-05-15T13:38:39.785287: Authorization = Basic d29ua2E6MTIzNDU2
Copied!
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.Last modified 2yr ago
Copy link