Skip to main content

Lifecycle Webhooks

Webhooks are HTTP callbacks that send data to a defined URL. Custom integrations may be built that respond to webhook event types from Lifecycle. When an event is triggered, the server sends an HTTP POST payload to the webhook’s defined URL.

With the received payload, your script may respond through the REST APIs.

Webhooks are defined by the following:

  • Webhook URL - the destination the webhook payload is sent.

  • Description - internal note for details on the use of the webhook.

  • Secret Key - Defined by the user, use a secret key to ensure the authenticity of the source.

  • Event Type - the event that occurs that is sent to the webhook.

Webhook Limitations

A limitation with webhooks is that there is no validation that the webhook was received by the destination. No re-attempt requests are made on failures.

We do not recommend using webhooks for auditing purposes as notifications may be lost due to latency or the remote service not being available.

Use the Audit Log for mission-critical message queuing for reporting and monitoring.

Webhook Access

Webhooks are created by System Administrators. Webhooks do not have a permissions model and will send HTTP requests for every configured event. The system consuming the webhooks will have access to all the data provided by the event types.

Create a Webhook

Use the following steps to create a webhook.

  1. Navigate to the Webhooks configuration from the System Preferences

  2. Select the Add a Webhook button

  3. Enter the webhook URL

  4. Select one or more Event Types

  5. Select Create

Use the Webhook configuration to edit and delete webhooks.

Working with HMAC Payloads

Hash-based message authentication code (or HMAC) is a cryptographic authentication technique that uses a hash function and a secret key. (source)

When enabling the secret key, the X-Nexus-Webhook-Signature header is sent with the webhook payloads to verify you are receiving an authentic message. When verifying the HMAC digest, the HmacDigest value should match the signature value.

Example script when receiving the webhook

Webhooks may be consumed with many tools. The following example is a simple service using node.js.

Run the following to initialize the environment. The secret key is saved to a setting.json file.

npm init
npm install express
npm install body-parser
echo {\"secretKey\":\"secretKey\"} > settings.json

Add the code below to a file named app.js, and run the webhook listener via the command: node app.js

const express = require('express');
const app = express();
const bodyParser = require('body-parser');
const settings = require('./settings.json');
const crypto = require('crypto');

app.use(bodyParser.json());'/', function(req, res) {
  const body = req.body;
  const signature = req.headers['x-nexus-webhook-signature'];
  var hmacDigest = crypto.createHmac("sha1", settings.secretKey).update(JSON.stringify(body)).digest("hex");

  console.log('Webhook received');
  console.log('Headers: ' + JSON.stringify(req.headers));
  console.log('Body: ' + JSON.stringify(req.body));
  console.log('HmacDigest: ' + hmacDigest);
  console.log('Signature: ' + signature);

app.listen(3000, function() {
  console.log('Server running on port 3000.');

Additional code may be added to further process the request by connecting with the server APIs to access details on the request.

Example Headers and Payloads

It is important to understand the payload being received. The event contains special headers that help describe the event.




This is the event type. For example, iq:policyManagement.


A unique UUID identifying the event.


The HMAC digest of the payload body, if an optional secret key has been configured.


The algorithm that calculates the HMAC digest of the body, currently only HmacSHA1.

Content-Type: application/json; charset=UTF-8
User-Agent: Sonatype_CLM_Server/1.24.0-SNAPSHOT (Java 1.7.0_25; Mac OS X 10.11.5)
X-Nexus-Webhook-Signature: 687f3719b87232cf1c11b3ef7ea10c49218b6df1
X-Nexus-Webhook-Id: iq:policyManagement
X-Nexus-Webhook-Delivery: 7f4a6dde-5c68-4999-bcc0-a62f3fb8ae48

A payload is returned with each event type.

    'applicationEvaluation': {
        'policyEvaluationId': 'debceb1d-9209-485d-8d07-bd5390de7ef5',
        'stage': 'build',
        'ownerId': '6a454175-f55d-4d33-ba44-90ac3af2e8b8',
        'evaluationDate': '2015-05-05T23:40:12Z',
        'affectedComponentCount': 10,
        'criticalComponentCount': 2,
        'severeComponentCount': 5,
        'moderateComponentCount': 3,
        'outcome': 'fail'

The data structure of the event payload differs by event.