Webhook
Last updated
Last updated
This node enables you to seamlessly send and request data to and from third-party services.
Click on the webhook module and enter the name of the webhook in the label field. This is not mandatory, but if you enter a label here, it should be something referring to the flow explaining what the API request is trying to achieve. In the 'URL Endpoint' entry box below you can put the selected endpoint.
"Failed" - In case there's an issue with the API request you are trying to send, e.g. the request didn't go through and the agent is waiting for a response for longer than 5 seconds or you didn't receive the correct parameters, you can use the "Failed" tab for error tracking. Simply decide on the behavior you'd like to happen in such a case.
For more information on our APIs, please click here.
GET - Retrieve some data from the external codebase
POST - Create some data for the external codebase
PUT - Update some data to the external codebase
DELETE - Delete data at the external codebase
PATCH - Apply partial modifications to data at an external codebase
Some third-party services might require you to add HTTP headers (HyperText Transfer Protocol) to the request. This is a data transmission standard that defines how servers and browsers send and interpret data. Additional information transferred along with the HTTP request for purposes such as authorization and identification.
Use Asynchronous Requests if you want the execution of the code not to be blocked regardless of the response.
Insert your JSON, HTML, text, X-WWW-FORM-URLENCODED, or XML file here if your request requires it. These code formats computers use to send information back and forth.
Not all API Requests will require a body. It is usually only relevant if you’d like to pass more parameters along, other than the query parameter in the Request Mapping.
In the Query Parameters section, enter the parameters you would like to send in your query.
You can either keep the value empty and have the user fill it during the conversation or you can add the value if you want to predefine it. Use $PARAM_NAME if you want to either take the value from the parameters that you prepopulated in the parameter section or if you want the user to fill the parameter during the conversation
Response Mapping defines the way you receive the third party’s response.
Define the Object Path and the right parameter you’d like to send the value to. We support XML as well as JSON as part of the response mapping.
The studio supports two response mapping types, xml and json.
To get for example, the Tove(note.to)value from the xml response, the value of the object path needs to be "note.to" or note['to']
To get for example the 1 (data.userId) value from the json response, the value of the object path needs to be "data.userId" or data['userId']
To get 1, for example, the (first item userId property) value from the json response, the value of the object path needs to be "$[0].userId" or $[0]['userId']
Need your webhook to run in the background whilst the rest of your flow continues? Simply toggle the asynchronous request within your webhook to allow the flow to proceed without depending on the node.
Now you have the ability to set the webhook time out to any amount of time between 10 to 25 seconds. As per default, the slider will be set to 10 seconds for each webhook node.
Once you have added all your request information, you can test if the webhook node is being executed correctly, by clicking on "Test Request" on the top right of the node settings.
In case your service requires whitelisting of our IPs, please use the following:
For EU-based agents Frankfurt: 18.198.250.71 18.156.30.186 18.195.173.181
For US-based agents
Virginia: 54.90.42.141 54.88.7.65 52.44.45.61
Webhook signing is a feature that allows your integrated application to verify that the request has been sent from Vonage and has not been tampered with in transit.
Whilst receiving a request, the Webhook will include a JWT token in the authorization header which is signed with your signature secret (which can be found under signed Webhooks in the API settings on the Nexmo dashboard).
How to enable Webhook signing
Webhook signing is enabled by default for voice agents built after June 2022. If your agent was built before this time period, follow the process listed below:-
Log into your dashboard
Go to the application settings
Select the appropriate application
Select “Edit”
Scroll down to “Capabilities”
Under the Voice capability select “Show Advanced Features”
Select the “Use signed Webhooks” checkbox.
How does the Webhook signing work?
On the Vonage AI side there is one part to the process - Validating the request to ensure that no tampering has occurred.
Validation of Request
To verify the request, Webhook signing involves a JWT token in the authorization header. In order to identify which signature secret has been used to sign the request, check the API key which is included in the JWT claims.
To learn more about decoding Webhook signing, please visit this page.
You can now decide to change the course of your conversation based on the status of your Webhook! You can specify individual codes or code classes (e.g. 3xx to refer to codes from 300 to 399) to decide the turn of the conversation in each scenario.
Here's how to go about it:
The Response status code section is available within the Webhook node drawer.
The default output takes into account all successful 2xx responses (status code 200 to 299).
You can specify either:-
Individual codes: E.g. 301, 500, 400, etc.
Code Classes: E.g. 4xx (which would mean all codes from 400 to 499), 5xx (all codes from 500 to 599), etc.
You can also save the resulting status code in a parameter for further use.
Please make sure to create a parameter with the sys.any or sys.number entity type to save your response code.
