Webhook event triggers

Webhook event triggers listen to events from event sources such as webhook endpoints and deployment providers to start releases.

1. Subscribe to an event source, defined in the Webhooks and Events section of the Connections screen and the folder Configuration tab.
2. React to events published by that event source by creating releases.
3. Configure the create release action by populating the required template variables according to rules that you define. See mapping properties for more information.
4. Create releases as soon as the event arrives with the values populated in the mapping process.

Configure Event-driven Release Orchestration

With Live Deployments, you can listen to deployment events from external tools like Digital.ai Deploy and ArgoCD and view live updates in Release.

As you make external deployments part of the release flow, even when they are not orchestrated by Release, you can also embed live deployment events in your release process using triggers.

Deployment Provider Event Source Properties

Here's the list of deployment provider event source properties that you can use to build your filter rules:

Property	Description
operation	Deployment operation such as create, remove or update deployment
configId	Status Webhook Event Source Configuration ID associated with the deployment
applicationCuid	Application correlation ID
applicationTitle	Application title
applicationSource	Application source associated with the event
environmentCuid	Environment correlation ID
environmentTitle	Environment title
deploymentTarget	Deployment target associated with the event
deploymentState	Snapshot state of deployment

Create a Webhook Event Trigger

Once you have defined an HTTP Endpoint for Webhooks or configured a deployment provider, you can create a webhook event trigger.

1. In the sidebar, under the Overview group, click Folders.
2. Select or create a new folder, select or create a new Template.
3. Add some variables to the template.
4. Navigate to the Triggers tab of the folder.

   Note: You can also create a trigger from inside a template. Select Triggers from the sidebar and click Add trigger. The trigger form will be shown with the template preselected. The remaining steps are the same as below.

5. Click Add trigger.
6. Select the Webhook event trigger option for the Trigger type field.
7. Give it a title and a description, and ensure it is enabled.
8. Select the Event source this trigger should react to. The list will include all the event sources defined in this folder and its parents.
   • For HTTP event sources, use POST endpoints to pass any data.
   • For deployment provider event sources, you can track events related to deployments such as operation, configId, applicationTitle, environmentTitle, and deploymentState.
9. Create a Filter rule if you want to conditionally execute the trigger.
10. Select a previously created template from the current folder.
11. In the Release title, you can either enter a title manually or click to select a property from the event body (or a folder/global variable) to populate the title.
    • For HTTP event sources, use properties from the webhook's JSON body.
    • For deployment provider events, properties like applicationTitle, environmentTitle, and deploymentState can be used. See Deployment Provider Event Source Properties.
12. In Tags, either enter a list of new tags separated by pressing Enter, or click to select a source to populate tags.
13. If there are template variables, the fields will already be populated with the default values. You can either overwrite this or use the icon to select a source to populate the variables.
14. Click Save.

Note: To trigger a release when a deployment succeeds, select a deployment provider event source and set up filters to capture the deploymentState as SUCCESS.

Filtering

It is possible to conditionally execute a trigger depending on the data inside the webhook event. The filter has access to folder and global variables, the content of the HTTP request (headers, parameters, and body), and deployment provider event data. There are three ways to create a filter: Visual designer, Jython expression, or Groovy expression.

Please note that if a property path referenced by a filter is not present, an exception will be thrown and the trigger will not execute. Use language native capabilities (Groovy Elvis operator) or order conditions accordingly (Visual designer with Object condition) to prevent that from happening.

The Groovy and Jython filters execute in a restricted sandbox without access to Digital.ai Release APIs.

Visual Designer

The visual designer simplifies creating filters by allowing you to add multiple conditions. For both HTTP and deployment provider events, you can compare JSON properties to specific values. The trigger will execute only if all conditions evaluate as true.

1. In the Filter rule field, select Visual designer from the dropdown.
2. Select the JSON type you want the condition to compare against.
3. For HTTP events, select one of the objects event., headers., or parameters. from the drop-down.
4. For deployment provider events, select event. (for example, event.applicationTitle, event.deploymentState). See Deployment Provider Event Source Properties.
5. In the second field, choose a comparison operator (for example, is equal to, contains).
6. In the third field, input a static value or use a variable to compare the JSON value.
7. Click Add.

Condition types and operators

The following are available condition types with operators for conditions in the visual designer:

Text

Matches JSON string type. If the received value isn't a string, XLR will convert it. null will be converted to empty string.

Operators:

• is equal to: checks string equality.
• is not equal to: checks string inequality.
• contains: checks if received value contains substring.
• does not contain: checks if received value does not contain substring.

Number

Matches JSON number type. If the received value is a string, XLR will attempt to parse it as a number. Else an exception will be thrown.

Operators:

• is equal to: checks number equality.
• is not equal to: checks number inequality.
• is less than: checks if received value is less than specified value.
• is greater than: checks if received value is greater than specified value.

Date

Matches JSON string or number type. If the received value is a number, XLR will interpret is as Unix time in milliseconds. If the received value is a string, XLR will try parsing it as an ISO 8601 formatted date. Else an exception will be thrown.

Operators:

• is equal to: checks date equality.
• is not equal to: checks date inequality.
• is before: checks if received date is before the specified date.
• is after: checks if received date is after the specified date.

Boolean

Matches JSON boolean value. If the received value is a string "True"/"False" (case-insensitive), XLR will try to parse it as boolean. Else an exception will be thrown.

Operators:

• is equal to: checks boolean equality.

List

Matches JSON lists. If the received value is a string that contains a valid list inside, e.g. "[1, "abc", true]", XLR will attempt converting it to a list. null will be converted to an empty list. Else an exception will be thrown.

Operators:

• is equal to: checks set equality on received and specified lists.
• is not equal to: checks set inequality on received and specified lists.
• contains any of: checks if received list contains any of the elements in specified list.
• does not contain any of: checks if received list does not contain any of the elements in specified list.
• contains all of: checks if received list contains all the elements in specified list.
• does not contain all of: checks if received list does not contain all the elements in specified list.

Object

Matches any JSON property. This condition type exists to check if the property exists in the JSON, so no exception will be thrown if the property path is non-existing in the JSON object.

Operators:

• field is defined: checks if the JSON property exists and is not null.

Jython Expression

The Jython expression filter works similarly to the Task preconditions. If the script returns True, the trigger will be executed.

In the script, you can access the following properties:

• event: The parsed JSON body of the webhook event or deployment provider event.
• headers and parameters: The HTTP request headers and parameters for HTTP triggers.
• folderVariables and globalVariables: These are available in both HTTP and deployment provider triggers.

The event, headers, and parameters data can also be accessed using dot notation, such as event.commits[0].author. Regular dictionary access is also supported.

1. On the Filter rule field, select Jython expression from the dropdown.
2. Type in the Jython expression filter code
3. If the filter is a single line, the expression has to return a boolean value. If there is more than one line, you have to assign a boolean value to the variable called result.

Jython expression lets you to set up more advanced conditional logic for triggers. The properties you can access in the script depend on the event type:

• For HTTP events, you can access event, headers, and parameters, which refer to the parsed JSON body of the HTTP webhook, and HTTP-specific request details.
• For Deployment Provider events, you can access the event object, which includes deployment-related information such as operation, configId, applicationTitle, environmentTitle, and deploymentState. See Deployment Provider Event Source Properties.

When writing a Jython expression, you can either use a single-line expression returning a boolean or a multi-line expression where you assign a result to the variable result.

Jython Expression Examples:

• For HTTP events: This script checks if the sender.login property in the incoming HTTP event is trustedUser. If true, the trigger will execute.

  if event.store.book[0].price == '${folder.expectedPrice}':
  result = True
  else:
  result = False

  For deployment provider events: To filter a deployment event trigger for a specific version, define the event.applicationTitle, event.environmentTitle, and event.deploymentState.statusGroup.

  if event.applicationTitle == 'TestApp' and event.environmentTitle == 'DEV' and event.deploymentState.statusGroup == 'success':
  result = True
  else:
  result = False

Folder and global variables are also accessible in the script using XLR variable access syntax, e.g. ${folder.var}. Variables referenced in this way are resolved in the filter script before script execution. This allows for some rudimentary expression reuse by having common filtering expressions stored into global or folder variables.

Groovy Expression

The Groovy expression filter works same as the Jython expression filter with the same properties accessible in the Groovy expression filter, where they are stored as Groovy maps.

Groovy Expression Examples:

For an HTTP event

if (headers['X-GitHub-Event'] == 'pull_request'
    && event.pull_request.labels.find { it.name == 'run_tests' }) {
 result = true
} else {
 result = false
}

For deployment provider event

if (event.applicationName == 'MyApp'
    && event.environmentTitle == 'development'
    && event.deploymentState.statusGroup == 'success') {
    result = true
} else {
    result = false
}

Mapping JSON Properties to Template Variables

Note: It is possible to bind only webhook body data to template variables and URL parameters. Headers can only be used in filtering.

Webhook JSON body values can be obtained from the event variable using JSONPath syntax. You can either access the variable using XLR variable syntax (${event.sender.login}), or directly map JSON value to XLR variable (XLR will do type conversions to the best of its ability).

If the referenced field is not present, an exception will be thrown and the trigger will not execute.

Example of mapping webhook JSON to Template variables

Webhook Event Permissions

Webhook event triggers have the same permissions as other trigger types. Users should have "Manage triggers" permissions to create or edit webhook event triggers.

When creating or editing a webhook event trigger, it is important to note the permissions required for your webhook to function correctly. Ensure that the webhook has access to the necessary event sources, including both HTTP endpoints and deployment providers. This includes:

• For HTTP webhooks: Ensure that the HTTP endpoint has been correctly configured and accessible, with the necessary permissions for the events being sent.
• For Deployment Providers: Ensure permissions are correctly set for the deployment provider being used. This includes access to the environments, applications, and deployment states relevant to the events being triggered.

Test Run Webhook Event Trigger

You can test the created webhook trigger on a dummy event to check its correctness. This will not create a release or be shown in the activity logs. Click on the top right Test run button to open the test run dialog.

You can define the HTTP headers, parameters, and JSON of the event during test run. On the right side the filtering and property mapping results will be displayed after the Run button is pressed.