Webhooks

Webhooks are an easy way to integrate Moveo.AI with your own system, providing personalization or more complex interactions 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.

Types of Webhooks

Moveo.AI supports two types of webhooks:

Dialog Webhooks

Dialog webhooks are triggered as dialog actions within your AI Agent conversations. They allow you to:

• Validate information collected from the user
• Send requests to external applications (checking customer status, inventory, etc.)
• Trigger SMS notifications or OTP verification
• Perform real-time integrations during conversations

Event Webhooks

Event webhooks are triggered by specific conversation events and provide different payload structures. They include:

• First message: Triggered when a user starts a new conversation
• Pre message: Triggered before processing a user message
• Post message: Triggered after processing a user message

Verifying Origin

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

NodeJS

hmac.js

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

Python

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 to verify callbacks 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"
      }
    ]
  }
}

Error Handling

If error HTTP codes 5xx are received as a response to the POST calls, Moveo.AI will try to resend the payload three times before giving up.

Response Requirements

All webhooks expect a response from your server:

• 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

Create a webhook

Perform the following steps to create a webhook:

Step 1

Navigate to the AI agent > Workflows → Webhooks.

Step 2

Select the type of the webhook.

Step 3

Configure the name, URL and the verification token. You can also add more custom request headers.

Step 4 (Optional)

For dialog webhooks, drag the webhook action and select the webhook to the desired workflow.

Next Steps

• Learn about Dialog Webhooks - Triggered during dialog flows
• Learn about Event Webhooks - Triggered by conversation events