Webhooks

Webhooks are an easy way to integrate Moveo.ai with your own system, to provide personalization or more complex interaction with your users. Moveo.ai sends information to your custom endpoint using simple HTTP POST calls whenever a webhook action is triggered within your dialog.

As an example, you can use a webhook to do on of the following types of things:

  1. Validate information that you collected from the user.
  2. Send requests to an external application. For example, you might check on the application status of a customer or access your inventory to see if a product is available for shipping.
  3. Trigger a SMS notification or OTP verification

Verifying Origin

Each callback will contain a signature on the JSON passed to the callback. The signature is HMAC with SHA256 that will use the webhook verification token as the key and the JSON as the value. The result will be passed as HTTP Header X-Moveo-Signature so the receiver can determine the origin of the message.

hmac.js
import crypto from "crypto";
function encodeHMAC(data: crypto.BinaryLike, secret: string): string {
return crypto.createHmac("sha256", secret).update(data).digest("hex");
}

Whitelisting IPs

We strongly discourage IP allow lists and encourage customers instead to verify the callbacks by using HMAC Signed Callbacks.

If you are restricting inbound traffic allow the following IPs:

  1. 18.192.167.150
  2. 18.198.233.220
  3. 3.66.239.254

Setting Custom Headers

By enabling the Customize Headers section, you can add any headers that you want to pass to the service during the webhook call.

The only headers that you are not allowed to add are:

'Connection',
'Content-Disposition',
'Content-Encoding',
'Content-Length',
'Content-Type',
'Host',
'Upgrade',
'Accept'

Receiving Calls

Whenever a webhook is triggered Moveo.ai sends the following payload in JSON format to your Webhook URL.

Example

{
"channel": "web",
"session_id": "00d2ff33-706e-4a2c-8544-df6c9d0c1ecf",
"brain_id": "d3d08940-f0ef-42e0-993c-1bea065dcqwe",
"lang": "en",
"context": {
"total_months": 3,
"destination": "England",
"sys-unknown_counter": 0,
"sys-channel": "web",
"total_expenses": 500
},
"input": {
"text": "Hello, my name is George and I would like to go for erasmus"
},
"intents": [
{
"intent": "erasmus",
"confidence": 0.89
}
],
"entities": [
{
"entity": "firstname",
"value": "George",
"start": 18,
"end": 36,
"confidence": 1,
"type": "user"
}
],
"tags": ["erasmus", "destination"],
"debug": {
"dialog_stack": [
{
"node_id": "35411a26-cff7-4fb3-a2e9-0e8e6ada048a",
"name": "greetings"
},
{
"node_id": "a85b10e8-e7f3-40df-9715-196c4eae5f14",
"name": "plan_erasmus"
}
]
}
}

In the case of receiving error HTTP codes 5xx as a response to the POST calls, Moveo.ai will try to re-send the payload three times before giving up.

Reference

Outer Level

ProperyTypeDescription
channelstringChannel name the message is coming from ("viber", "web" etc.)
session_idstringThe ID representing the user that triggered the webhook call
brain_idstringThe ID representing the brain for the webhook call
verify_tokenstringThe verify token you specified in the webhook configuration
contextCONTEXTContext variables that have been collected for that user so far
inputINPUTThe user input that triggered the dialog node
intentsINTENTList of intents recognized, sorted by confidence
entitiesENTITYList of entities recognized in the user input
debugDEBUGInformation related to debugging the Moveo.ai dialog state

Context

Context consists of key-value pairs with the keys representing context variables names and values capturing the user input.

Input

ProperyTypeDescription
textstringThe text that was typed by the user

Intent

ProperyTypeDescription
intentstringThe intent name
confidencefloatThe confidence for that intent (between 0 and 1)

Entity

ProperyTypeDescription
entitystringThe entity type
valuestringThe entity value from the user's input
startintegerStart index of the value within the user's text
endintegerEnd index of the value within the user's text
confidencefloatEntity detection confidence
typestringType of entity (ie. "user", "system" etc.)

Debug/Dialog Stack

ProperyTypeDescription
node_idstringThe node id as defined in the dialog
namestringThe node name as defined in the dialog

Sending Replies

With each reply you can send back messages and information. Whenever you receive a webhook call, Moveo.ai:

  1. Expects a response in the same HTTP call.
  2. Expects a 200 response code from your server.
  3. Expects a response from your server within 8 seconds or less.

Example

{
"responses": [
{
"type": "text",
"texts": ["Your total seems to be 100 dollars!"]
},
{
"type": "text",
"texts": [
"Would you like to receive a discount by filling out a survey?"
],
"options": [
{
"text": "yes",
"label": "Yes!"
},
{
"text": "no",
"label": "No, thanks"
}
]
},
{
"type": "image",
"name": "Aristotle",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/a/ae/Aristotle_Altemps_Inv8575.jpg/1024px-Aristotle_Altemps_Inv8575.jpg",
"size": 10
},
{
"type": "url",
"url": "https://www.google.com/maps/place/Athens,+Greece/@37.9908997,23.7033199,13z/data=!3m1!4b1!4m5!3m4!1s0x14a1bd1f067043f1:0x2736354576668ddd!8m2!3d37.9838096!4d23.7275388"
},
{
"type": "audio",
"name": "SoundHelix",
"url": "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
"size": 12
},
{
"type": "video",
"name": "Apple Commercial",
"url": "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerMeltdowns.mp4",
"size": 2299653
},
{
"type": "file",
"name": "Riemann.pdf",
"url": "https://www.claymath.org/sites/default/files/official_problem_description.pdf",
"size": 10000000
},
{
"type": "event",
"trigger_node_id": "56d7a633-60c4-4206-86d3-9aaf1e77c1c6"
},
{
"type": "carousel",
"cards": [
{
"media": {
"url": "https://res.cloudinary.com/dey0ylu2x/image/upload/v1607095100/carousel/image1.png",
"type": "image"
},
"title": "Example title",
"buttons": [
{
"type": "postback",
"label": "Button",
"value": "hello"
}
],
"subtitle": "Example subtitle",
"default_action": {
"type": "phone",
"value": "6900000000"
}
},
{
"media": {
"url": "https://res.cloudinary.com/dey0ylu2x/image/upload/v1607095100/carousel/image2.png",
"type": "image"
},
"title": "Example title",
"buttons": [
{
"url": "https://integration-guides.vercel.app/demo/demoForm",
"type": "webview",
"label": "Open Webview!"
},
{
"url": "https://moveo.ai/en",
"type": "url",
"label": "Button"
},
{
"type": "phone",
"label": "Button",
"value": "2108143234"
}
],
"subtitle": "Example subtitle",
"default_action": {
"type": "postback",
"value": "hello"
}
},
{
"media": {
"url": "https://res.cloudinary.com/dey0ylu2x/image/upload/v1607095100/carousel/image3.png",
"type": "image"
},
"title": "Example Webview",
"buttons": [
{
"url": "https://www.google.com",
"type": "url",
"label": "Button"
}
],
"subtitle": "Example subtitle webview",
"default_action": {
"url": "https://integration-guides.vercel.app/demo/demoForm",
"type": "webview"
}
}
],
"action_id": "6bd27163-2aa9-476b-8f53-8bf5300e1882"
}
],
"output": {
"total_expenses": 100
}
}

Reference

Outer Level

ProperyTypeDescription
responsesRESPONSESList of responses that Moveo should use to respond to the user
outputdictionaryKey-value pairs that can be used to update user context variables

Responses

ProperyTypeDescription
typestringIntegration type
textsstringList of texts that should be used to reply
namestringMedia name
urlstringURL to be used for url type
sizestringMedia size in bytes
trigger_node_idstringNode id to be triggered for event type

Validation

You can use the Debug section within from the Try-it functionality to debug any issues that Moveo might have encountered when displaying your webhook responses.

How to create you own webhook

You can find a comprehensive set of examples where webhooks are used here.

Last updated on