When connecting to destinations such as webhooks or Slack, you'll be able to create powerful custom integrations via the Integrations screen. UpGuard's integration system allows for a wide variety of triggers, each with their own data structure and available variables.
To give our users as much flexibility as possible when creating integrations, we support the open-source Liquid templating language. Using the variable data included in each trigger can be very simple, or more complex, depending on your requirements and the complexity of the trigger.
Integration trigger structure
To understand how Liquid syntax works, it's good to first understand how the data 'payload' in our integration triggers are structured. When creating an integration, we show you a breakdown of the variables, and a full example of the raw payload data. See this example below:
The "Variables" section breaks down some sample values and the corresponding template variable. You can simply copy and paste the template variable into your message. These variables cover simple data types such as text or numbers.
In the above example, you can see the full JSON representation of the data payload. The top level object is notification. There is a child of that object called context, which has its own children too. Liquid uses dot syntax to access children of objects, and surrounds any variable declarations in curly braces. So in the above example, to include the value of the Domain field in your message, you would use {{notification.context.Domain}} in your message.
Simple data types
Simple types such as text or numbers can generally be used by simply copying the variable name from the table that we provide, and pasting it into your message where you want it to appear. Continuing with the above payload example, if you set your message to:
New risks have been introduced for {{notification.context.Domain}}.
When the integration is triggered for the domain 'example.com', the message would come through as:
New risks have been introduced for example.com.
Array types
Some triggers contain multiple items within a single field, contained in an array, denoted by square brackets.
These fields can be iterated over within a message by using a for loop.
Using the example above, we might want to create a list based on all the items in the notification.context.RisksSummary array. To do this, we create a loop that executes for every item in the array:
{% for risk in notification.context.RisksSummary %}
* {{risk.Title}} (Severity: {{risk.Severity}})
{% endfor %}
When the integration is triggered and the RiskSummary field includes some risks, the message could come out as:
* SSL not available (Severity: 5)
* SPF not enabled (Severity: 4)
Advanced usage
The examples above should cover your needs for most cases, but Liquid syntax is very powerful, supporting control flow, iteration, and a range of filters.
Consult the Liquid documentation for full details.
Related Articles