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.
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.
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:
Whenever a webhook is triggered, Moveo.AI sends a payload of the following format (JSON) to your webhook URL.
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.
|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 consists of key-value pairs with the keys representing context variables names and values capturing the user input.
|text||string||The text that was typed by the user|
|intent||string||The intent name|
|confidence||float||The confidence for that intent (between 0 and 1)|
|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.)|
|node_id||string||The node id as defined in the dialog|
|name||string||The node name as defined in the dialog|
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.
|responses||Responses||List of responses that Moveo should use to respond to the user|
|output||dictionary||Key-value pairs that can be used to update user context variables|
|texts||string||List of texts that should be used to reply|
|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|
You can use the Debug 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.