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.

You can use a webhook to do one of the following types of things:

Validate information that you collect from the user.
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.
Trigger an SMS notification or OTP verification.

Verifying Origin

Each callback contains 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 is passed as HTTP Header X-Moveo-Signature so the receiver can determine the origin of the message.

NodeJS
Python

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

hmac.py
import hashlib
import hmac
def encode_hmac(verify_token: bytes, req_body: dict) -> str:
  body_bytes = json.dumps(req_body).encode("utf-8")
  return hmac.new(token, body_bytes, hashlib.sha256,).hexdigest()

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, you should allow the following IPs:

18.192.167.150
18.198.233.220
3.66.239.254

Receiving Calls

Whenever a webhook is triggered, Moveo.AI sends a payload of the following format (JSON) 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",
    "sys-user_message_counter": 1,
    "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

Property	Type	Description
channel	string	Channel name the message is coming from ("viber", "web" etc.)
session_id	string	The ID representing the user that triggered the webhook call
brain_id	string	The ID representing the brain for the webhook call
verify_token	string	The verify token you specified in the webhook configuration
context	Context	Context variables that have been collected for that user so far
input	Input	The user input that triggered the dialog node
intents	Intent	List of intents recognized, sorted by confidence
entities	Entity	List of entities recognized in the user input
debug	Debug	Information 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

Property	Type	Description
text	string	The text that was typed by the user

Intent

Property	Type	Description
intent	string	The intent name
confidence	float	The confidence for that intent (between 0 and 1)

Entity

Property	Type	Description
entity	string	The entity type
value	string	The entity value from the user's input
start	integer	Start index of the value within the user's text
end	integer	End index of the value within the user's text
confidence	float	Entity detection confidence
type	string	Type of entity (ie. "user", "system" etc.)

Debug/Dialog Stack

Property	Type	Description
node_id	string	The node id as defined in the dialog
name	string	The 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:

Expects a response in the same HTTP call.
Expects a 200 response code from your server.
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": "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",
              "type": "url",
              "label": "Button"
            },
            {
              "type": "phone",
              "label": "Button",
              "value": "2100123456"
            }
          ],
          "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"
    }
  ],
  "context": {
    "total_expenses": 100
  }
}

Reference

Outer Level

Property	Type	Description
responses	Responses	List of responses that Moveo should use to respond to the user
context	dictionary	Key-value pairs that can be used to update user context variables

Responses

Property	Type	Description
type	string	Integration type
texts	string	List of texts that should be used to reply
name	string	Media name
url	string	URL to be used for url type
size	string	Media size in bytes
trigger_node_id	string	Node ID to be triggered for event type

warning

You cannot directly set the user variable. Instead, if you want to return a field such as the user's name, use the following approach:

Instead of:

context: {
  user: {
    display_name: "John Doe";
  }
}

Use:

context: {["user.display_name"]: "John Doe"}

Validation

You can use the Details section within from the Test functionality to debug any issues that Moveo might have encountered when displaying your webhook responses.

How to create your own webhook

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

Verifying Origin​

Whitelisting IPs​

Receiving Calls​

Example​

Reference​

Outer Level​

Context​

Input​

Intent​

Entity​

Debug/Dialog Stack​

Sending Replies​

Example​

Reference​

Outer Level​

Responses​

Validation​

How to create your own webhook​

Verifying Origin

Whitelisting IPs

Receiving Calls

Example

Reference

Outer Level

Context

Input

Intent

Entity

Debug/Dialog Stack

Sending Replies

Example

Reference

Outer Level

Responses

Validation

How to create your own webhook