Overview 

If you want to connect Vivantio to an external tool that isn’t supported out-of-the-box, Webhooks and Web Methods are the first point of call. Rather than developing custom middleware that uses the API, Webhooks and Web Methods allow you to set up both incoming and outgoing data transfer between Vivantio and the system of your choice, without writing any code or deploying additional applications.

Webhooks support data going out of Vivantio and into an external systems. You can set up a Webhooks to send data in the format your other system is capable of receiving and define actions to take based on the response.

Before you start building a Webhook we recommend you review our article on using webhooks and web methods with a worked example. The article also has a template to help you plan your own integration. 

These are the things you need to consider before you start building the integration:

• What data is going to be sent?
• When should that data be sent i.e. will a technician manually trigger the web hook or should it be triggered automatically when conditions are met?
• What data should be returned in response (e.g. an ID number from the receiving system)? For example if you need to subsequently update the record in the external system?
• How will Vivantio authenticate against the external system?

Integrations in Vivantio - a video overview of Intergrations providing some examples

Creating a Webhook

Admin > Integration & API > Web Methods.

Basic details tab

After adding a new Webhook you will be presented with the screen below. 

• Name – this is a mandatory field and needs to be user friendly, especially if it is being made available to technicians as an action on the ticket, e.g. Send to customer x. 
• Enabled – whether the webhook is available to be triggered by a technician or a business rule. 
• Request URL – this is a mandatory field and it should be supplied by the receiving external system. You cannot save the webhook without completing this field. The request URL can be made dynamic by including other fields such as a custom field which has captured the external system id. This is useful if updating an existing ticket e.g. https://externalsystemurl/{{ticket.thirdparty.sysid}}
• Encoded URL parameters- if the url contains encoded URL parameters such as "/?username=test" tick this box
• HTTP Method  - select as appropriate:
  • POST - request server accepts data encoded in body
  • GET - retrieves data only
  • PUT - requests data to be stored under URI
  • DELETE - deletes specified resource
  • PATCH - partially modifies a resource
• Authentication Type - select as appropriate,
  • No Authentication -  if there are no login details to provide, e.g. if using access key,
  • Basic - provide the user name and password,
  • NTLM - provide the username, password and domain. 
• Username and Password - if the outgoing request requires authentication these must both be completed. Password will show as blank after the update has been saved.  
• Domain - only required for NTLM

Response Content Type– set as advised by the receiving external system, options are:

• application/json - (javascript object notation)
• application/xml - (extensible markup language)
• application/x-www-form-urlencoded - (url encoded form)
• text/html
• Run Rules After Response Processed - if you have any trigger rules which need to act on the response values tick this box, for example if you want to assign to a group based on a value you receive or to apply a workflow.
• Action description - this will appear in the Ticket History when the web hook is fired. You can use fields in this box. 

Parameters tab

Define any parameters that you want the prompt the technician to complete when firing the webhook (these can also be completed based on the trigger rule firing the webhook). If there is no additional information to send to the receiving system you don't need to add any parameters. Any with default test will have a value populated automatically that can be changed. 

Click the Add button to add a parameter.

To complete the parameter details:

Name - the parameter name, this will display to the technician

Read only - if you are populating the field via a default source from elsewhere you may choose to make it read only so that the data cannot be changed. This is useful if you want to show the technician what data will be sent prior to the webhook being fired. 

Data type - Alpha Numeric is the only option to select

Display type - Freetext or Freetext (Multiline) - for larger quantities of text

Example of webhook parameters being captured following the trigger of a webhook. The customer reference is filled in manually and the Priority Name and Ticket ID are populated automatically and are read only, they are showing for the technicians reference. 

• Vivantio recommend that if you are going to receive updates from the external system you should consider including the ticket ID in the parameters sent  (this is different from the Display ID which is the ticket reference). The ticket ID provides a much more efficient method of matching tickets and reduces the risk of unintended impacts on performance. It is this value that you should use in the trigger rules etc. 

Request body tab

Select the type of request content, in the example below we are using json. Configure the body of the HTTP request to be sent, using double brace notation to embed parameter values or fields from the Ticket.

Body Template
The body of the request. You can use fields from the Ticket, or from Custom Forms on the Ticket, by specifying them like:

{{ticket.displayid}}
{{ticket.formname.fieldname}}

For Multi Line Custom Forms you can send the whole ‘Collection/Array’ from the Ticket by  specifying them like:

{{ticket.formname}}

               Example:

{

"ticketid": "{{ticket.displayid}}",

"linkedassets": “{{ticket.formname}}”

               }

               This will send all fields and all entries within the Multiline Form. E.g

{
               "ticketid": "IN164",

 "linkedassets": [
                              {

"asset": "P2425",
"assetrequestdate": "2025/04/23"
 },

                               {

                               "asset": "FH6354",

                               "assetrequestdate": "2025/04/30"

                              }

                                                ]

}

Response fields tab

If required, you can extract data from the response to your request and place them into custom form fields, so for example you might capture a reference number from the external system and use it to populate a custom field for future reference. In the example below the receiving system is sending us a value result.number and we are populating a Custom Field called VivantiotestID on the Custom Form called Integration with the data.

 

Select Tickets tab

Configure which Tickets the Webhook is available for. If the ticket does not match these conditions the webhook will not be available in the actions drop down list:

Click Save

Manually Firing Webhooks - Roles

Once you have set up the Webhook, you can then decide which roles will be available to fire the Webhook manually. If the Webhook will be fired based on a trigger rule you do not need to add any roles. 

Select the Webhook you wish to apply roles to.

Click the Roles button

Drag the applicable Available Roles to the Current Roles

Click Save

Technicians view

You’ll see the webhook appear in the Actions drop down on the Ticket Details page (and in this case also as a button):

 

Automatically Firing Webhooks - Trigger Rules

Alternatively to manually firing them off you can create a Trigger Rule to fire a webhook based on ticket conditions. Within the Trigger Rules, Execute Webhook is available as an Action Type, allowing for automated interaction with other systems. Find out more about Trigger Rules here. 

 

For example, you may have a trigger rule which triggers every time a matching ticket is updated and is currently e-bonded. Don't forget to exclude any updates made by the receiving system or you could get stuck in a loop!

For an example of setting up a full integration with another service desk system please follow this link. 

 

Further information about REST API's can be found in Swagger

 

Reviewed: 28 March 2023