HTTP Endpoints for Webhooks

Note: To pass any data, use only POST endpoints.

HTTP endpoints for webhooks allow you to listen to callback events from external sources such as Jira or GitHub.

HTTP endpoints for webhooks can use two methods:

• POST endpoints is the most common, and reacts to POST HTTP events. POST endpoints can only consume JSON payloads.
• GET endpoints reacts to GET HTTP requests. GET requests have by definition no content, and usually send information through URL parameters instead.

When setting up an HTTP endpoint for webhooks, the user is required to provide at least four pieces of information:

• HTTP method: GET or POST
• title: the name of the endpoint
• path: the last segment of the URL this endpoint should be accessible at. This path must be globally unique across the Digital.ai Release system.
• authentication method: the method to verify the identity of the sender. Depending which method is selected, more information might be required - a secret key, for example.

note

HTTP endpoints for Webhooks and Event sources require users to have the edit configuration permission. It is possible to bind only webhook body data to template variables and URL parameters. Headers can only be used in filtering.

As of 9.8, an additional field Request Retention was added. This specifies the maximum amount of requests to be kept in the database. The requests are currently used for webhook trigger execution logs purposes. You can modify the frequency at which the events will be cleaned up by changing the xl.features.webhooks.retention-policy.schedule property in XL_RELEASE_SERVER_HOME/conf/xl-release.conf configuration file by using a cron expression. The default value is "0 0 0/6 1/1 * ?".

Webhook URLs

The URL of an Digital.ai Release HTTP endpoint for Webhooks will have the following form: XL_RELEASE_URL/webhooks/${path}. For example, http://localhost:5516/webhooks/webhook1. If the version of Digital.ai Release has a non-root context such as http://localhost:5516/production-xlr/, then the endpoint will be http://localhost:5516/production-xlr/webhooks/webhook1.

Note: a localhost instance of Digital.ai Release will not be accessible from anywhere but the same machine where Digital.ai Release is running.

When configuring HTTP endpoints for webhooks, you also need to expose Digital.ai Release to the external system's network. This often means having Digital.ai Release, or some specific endpoints, reachable from the public internet. There are various possible ways to expose your Digital.ai Release system to an external system, and which approach you choose will depend on your infrastructure.

Webhook security

When configuring an HTTP endpoint for webhooks, it is required to select which type of authentication method to use to verify the identify of the sender and, in some cases - i.e. GitHub - also the integrity of the HTTP request's content.

Since opening an HTTP endpoint for webhooks in Digital.ai Release will expose the system to external HTTP requests, it is important to secure your connections. For example, if you use a publicly exposed endpoint, you should definitely avoid using the No authentication method.

The authentication method you use will depend entirely on which methods are supported by the external source that sends the requests.

Out of the box, and other than No authentication, only the GitHub authentication method is provided.

For quick and one-of authentication it is possible to use the Scripted Authentication (Jython) authentication method and write a Jython script that will decide if an incoming request is considered authenticated or not. Please keep in mind that a Jython script will always be slower than a dedicated JVM-based solution.

It is also possible to package a Jython script authentication method by extending the events.CustomJythonAuthentication type. This has the advantage of being much more user-friendly as it is possible to add custom properties to be used as configuration parameters for the script.

For more information, see webhook plugins.

Scripted Authentication (Jython)

This script should set the variable authenticated to either True or False.

It can access the properties of the HTTP requests by using the following variables:

• endpoint: the HTTP endpoint for webhooks that recived the HttpRequestEvent
• endpoint.title: the name of this HTTP endpoint for webhooks
• endpoint.path: the path of this HTTP endpoint for webhooks
• endpoint.method: the HTTP method of this HTTP endpoint for webhooks. Can be either POST or GET
• endpoint.authentication: the instance of the authentication method for this endpoint
• config: alias for endpoint.authentication, which contains the properties of this endpoint's authentication method configuration
• headers: the headers of the current HTTP request this script is authenticating (type: Python dictionary)
• parameters: the URL parameters of the current HTTP request this script is authenticating (type: Python dictionary)
• payload: the request body of the current HTTP request (type: String). Only available if endpoint.method is POST

Simple example:

global parameters

def get_tokens():
    return parameters['token'].split(', ') if 'token' in parameters else []

# True if the 'token' query parameter exists and one of its values matches 's3cr3t'
authenticated = 's3cr3t' in get_tokens()

Create an HTTP endpoint for Webhooks

To define an HTTP endpoint for Webhooks:

1. From the navigation pane, under the Configuration group, click Connections > Webhooks and Events, and then click HTTP Endpoint For Webhooks +.
2. Select either GET or POST Endpoint

3. Enter a name for this endpoint in the Title field
4. Enter a path for the endpoint to listen to. This will have the form XL_RELEASE_URL/webhooks/${path}. This path must be unique across the Digital.ai Release system. An error will notify the user if the chosen path is already taken upon saving.

5. Select an authentication method from the drop-down. For more information, see Webhook security:

• No authentication
• Github Authentication
• Scripted Authentication (Jython)

6. Enable the event (default)
7. Click Save.

You can add more endpoints as needed. They can also be added per-folder in the folder Configurations, provided their path is globally unique.

Once the endpoint is configured, you can use it as an event source when setting up webhook event triggers to create a release from a template. For more information, see Webhook event triggers.