Setup guide

Step 1: Create a custom integration

1. In the Moveo dashboard, go to Deploy → Connections.
2. Under Available, click Custom HTTP.

Step 2: Configure the webhook

1. Enter your Webhook URL — the HTTPS endpoint where Moveo delivers events.
2. Enter a Webhook secret — a string used to sign webhook payloads with HMAC-SHA256. Store this securely.
3. Click Save.

Step 3: Generate an API key

1. In the API Key section, click Generate.
2. Copy and securely store the API key. It is shown only once.
3. Use this key in the Authorization header for all inbound API requests.

Step 4: Configure optional settings

The dashboard shows only Session timeout. Set allowed_ips and subscribed_events in the integration config with the update integration endpoint. That endpoint needs a Moveo API key of the type Manage, not the integration key from step 3. Only Admins and Owners can create one. See API Keys.

• Allowed IPs — restrict inbound API access to specific IP addresses or CIDR ranges (e.g., 203.0.113.0/24). Leave empty to allow all IPs.
• Subscribed events — choose which webhook event types to receive. Leave empty to receive all events.
• Session timeout — set the session TTL in seconds (default: 86,400 = 24 hours).

Step 5: Test the integration

Send a test request to create a session and verify your webhook receives the bot response. See the complete example section.

---

Configuration options

Parameter	Type	Required	Default	Description
webhook_url	string	Yes	—	Your HTTPS endpoint URL for receiving events.
webhook_secret	string	No	—	Secret key for HMAC-SHA256 webhook signature verification. Maximum 256 characters.
allowed_ips	string[]	No	All IPs	IP addresses or CIDR ranges allowed to call the inbound API.
subscribed_events	string[]	No	All events	Event types to receive on your webhook.
session_timeout	integer	No	86400	Session TTL in seconds. Minimum: 60 (1 minute). Maximum: 1,296,000 (15 days).

Set a webhook secret

webhook_secret is optional, but leave it unset and Moveo signs every payload with an empty key — a signature anyone can reproduce, which makes the X-Moveo-Signature header worthless. Set a secret on any integration that handles real traffic.

---

Authentication

All inbound API requests require an API key in the Authorization header:

Authorization: apikey YOUR_API_KEY

If you configure an IP allowlist, requests from IPs outside the allowlist receive a 401 Unauthorized response. The allowlist supports both individual IPs and CIDR notation (e.g., 198.51.100.42 or 203.0.113.0/24).