Webhooks overview

Webhooks, introduced in Release 9.7, are able to trigger releases as a reaction to specific HTTP requests made by an external source. This can potentially reduce the load of Release, while also reducing the pressure on external systems caused by polling methods where release triggers had to actively make requests to the third party system.

The core components of Release webhooks are:

• HTTP endpoint for Webhooks
• Webhook event triggers
• Webhook event tasks
• Messaging system (JMS)

HTTP endpoints for Webhooks are event sources that listen to HTTP requests and publish events of type events.HttpRequestEvent.

Events encapsulate the data flowing from HTTP endpoints for webhooks and into webhook event triggers and tasks.

Webhook event triggers and tasks are event consumers. They subscribe to an HTTP endpoint for webhooks, and when a matching event arrives they execute their predetermined action.

Webhook event triggers create a release from a Template, like other trigger types.

Webhook event tasks will behave as gate tasks and transition to a Completed state.

HTTP endpoints for webhooks publish events to the messaging system's queue. Events in the messaging system's queue are picked up and dispatched to the webhook event triggers and tasks subscribed to the endpoint that published that event.

HTTP endpoint for webhooks

• HTTP endpoints for webhooks are Shared configuration items used to open a specific HTTP endpoint on Release.
• An HTTP endpoint for wbhooks can be listening to either GET requests with no content, or POST requests with a JSON payload.
• HTTP endpoints for webhooks are not protected by the regular system authentication, but they can be protected with custom authentication methods.
• The external system that is configured to send webhook events to Release must be able to reach Release.
• There are various possible ways to expose your Release system to an external system, and which approach you choose will depend on your infrastructure.

For more information, see HTTP endpoint for Webhooks.

Webhook event triggers

Webhook event triggers are a class of release triggers that execute upon receiving an event from the event source to which they are subscribed.

When configuring a webhook event trigger, the user can define, for each required template variable, which value to use. It can be a manually entered value, a value from a folder variable, a value from a global variable, or the value of a property of the received event.

Refer to the full article regarding Webhook event triggers for more information.

Webhook event tasks

Webhook event tasks are a type of custom script tasks that wait for a matching event from the event source to which they are subscribed.

Webhook event tasks act as gate tasks for external business events.

Refer to the full article regarding Webhook event tasks for more information.

Webhook messaging system

Event sources and webhook event triggers receive and publish events using a JMS queue.

Digital.ai Release ships by default with an embedded JMS messaging queue system. However, if you wish to use your own message system, you can configure the xl-release.conf file with the following options:

xl.queue {
        embedded = true
        # the following properties are only used when embedded = false
        url = "tcp://jms.my-intranet:61616"
        username = "myUsername"
        password = "myPassword"
        queueName = "myQueueName"
    }

If you want to use the webhooks feature in a High Availability (cluster mode) setup, the JMS queue cannot be embedded. It must be external and shared by all nodes in the Release cluster.

In cluster mode, xl.queue.embedded must be set to false and the rest of the xl.queue configuration section must be properly configured to point to an existing JMS queue.

Note: Release connects with external messaging queues with only amqp protocol. Other protocols like UDP, TCP, JGROUP, etc are not supported as of now.

Connect Release with ActiveMQ and RabbitMQ

Below given is an example for to connect XLR with ActiveMQ and RabbitMQ

ActiveMQ example:

Edit conf/xl-release.conf file to include queue configuration details.

xl.queue {

        embedded = false

        # the following properties are only used when embedded = false

        url = "tcp://ip_or_hostname:61616"

        username = "myUsername"

        password = "myPassword"

        queueName = "myQueueName"

    }

RabbitMQ example:

Enable rabbitmq_amqp1_0 plugin on the RabbitMQ node using the below command:

rabbitmq-plugins enable rabbitmq_amqp1_0

Edit conf/xl-release.conf file to include queue configuration details.

xl.queue {

        embedded = false

        # the following properties are only used when embedded = false

        url = "amqp://ip_or_hostname:5672"

        username = "myUsername"

        password = "myPassword"

        queueName = "myQueueName"

    }

Note: No need to add any jar file of ActiveMQ and RabbitMQ in the release lib folder to connect with XLR.

Webhook samples

See the xlr-webhooks-samples repository for example webhook integrations in the form of as-code templates.