Webhook
Last updated
Was this helpful?
Last updated
Was this helpful?
This node enables you to seamlessly send and request data to and from third-party services.
"Failed" - In case there's an issue with the API request you are trying to send, e.g. the request didn't go through or 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 behaviour you'd like to happen in such a case.
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 is transferred along with the HTTP request for purposes such as authorization and identification.
Insert your JSON, HTML, text, X-WWW-FORM-URLENCODED, or XML file here if your request requires it. These code formats are commonly used 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 caller 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 pre-populated 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 store the value in. We support XML as well as JSON as part of the response mapping.
The studio supports two response mapping types, xml and json.
Need your webhook to run in the background whilst the rest of your flow continues? Simple, 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 Requests
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.
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 the response code.
To learn more about decoding Webhook signing, please visit .
