How to use webhook notifications

3 minute read
This is a Limited Availability feature. This feature is still being tested, and may be changed or removed from the product in the future. Limited support is provided for Limited Availability features.
Webhooks are available only with the DevOptics Premium version.

Webhooks provide a way to connect DevOptics value streams with a third-party application to receive notifications about the following gate events:

  • Gate status changes

  • Gate failures

  • Gate successes

  • Runs for any jobs associated with a gate

With webhooks you can receive notifications that are relevant to your work without having to constantly monitor your value streams. You can be notified when an issue arises that needs your attention so that you can address it immediately, thereby reducing downtime.

The notifications include the following types of information:

  • Name of the value stream

  • Phase name

  • Gate name

  • Type of event that occurred

  • Last run ID

  • Commit ID

  • Ticket ID

The following example shows a sample JSON payload from DevOptics:

{
  "message": "Value Stream: M2 Demo, Phase: Build, Gate: Build is now in a successful state, last runId: 4.",
  "commits": [
    {
      "commitId": "3489e39b2429e36c14c13c02cd7032fd6a2c277b",
      "repoUrl": "https://github.com/cloudbees/devoptics-demo",
      "repoBranchName": "master",
      "commitUrl": "https://github.com/cloudbees/devoptics-demo/commit/3489e39b2429e36c14c13c02cd7032fd6a2c277b"
    },
    {
      "commitId": "17ebac52ecc66aad183d96c3dad87fd6f2cbfb76",
      "repoUrl": "https://github.com/cloudbees/devoptics-demo",
      "repoBranchName": "master",
      "commitUrl": "https://github.com/cloudbees/devoptics-demo/commit/17ebac52ecc66aad183d96c3dad87fd6f2cbfb76"
    },
    {
      "commitId": "5811f962d2057d2f246eed5dbd6b00872bad5752",
      "repoUrl": "https://github.com/cloudbees/devoptics-demo",
      "repoBranchName": "master",
      "commitUrl": "https://github.com/cloudbees/devoptics-demo/commit/5811f962d2057d2f246eed5dbd6b00872bad5752"
    }
  ],
  "ticketIds": [
    "DEVOPTICS-4",
    "DEVOPTICS-6"
  ],
  "timestamp": 1556027155379,
  "text": "Value Stream: M2 Demo, Phase: Build, Gate: Build is now in a successful state, last runId: 4.",
  "metadata": {},
  "devOpticsId": "cloudbees",
  "webhookUrl": "https://webhook.site/c89dc55e-2376-4b69-9c11-0cfff522c48f",
  "phaseName": "Build",
  "valueStreamName": "Loki M2 Demo",
  "valueStreamUrl": "http://devoptics.cloudbees.test:10999/u/application/1386979231",
  "version": 1,
  "valueStreamId": "1386979231",
  "phaseId": "build",
  "gateId": "build",
  "runId": "4",
  "gateName": "Build",
  "notificationType": "GATE_SUCCESS"
}

The following example shows a sample notification:

Value Stream: Pipeline Test, Phase: Development, Gate: Development is now in a successful state, last runId: 49.

Prerequisites for webhook configuration

Before you can add a webhook to DevOptics, you should verify that your preferred third-party application is configured to accept incoming HTTP POST requests. Most popular third-party applications are already configured to receive these types of notifications. Follow the instructions provided by the application. The DevOptics JSON payload is compatible with many commonly used APIs like Slack, but many integrations and customizations will require manual parsing and construction of notifications.

After you verify that your preferred application is configured to accept incoming HTTP POST requests, you can add a webhook to your value streams.

Adding a webhook

Follow these steps to add a webhook to any gate in any of your value streams. You can add multiple webhooks to a gate.

  1. On the Value Streams screen, select the value stream for which you want to add a webhook.

  2. Select the gate for which you want to add a webhook.

  3. In the right panel, scroll to the bottom of the panel, and then click Add new webhook. add new webhook

  4. In Webhook URL, type the URL from the third-party application you are using.

  5. In Label, type a name to describe this webhook. This label appears in the Webhooks section of the Gate side panel.

  6. In Events to send, select the type of event for which you want to trigger a notification.

  7. Click Save.

Editing a webhook

You can change any of the settings for a webhook.

  1. On the Value Streams screen, select the value stream that contains the webhook you want to edit.

  2. Select the gate that contains the webhook you want to edit.

  3. In the right panel, scroll to the bottom of the panel, and then click the name of the webhook you want to edit.

  4. Change the settings as needed.

  5. Click Update.

Deleting a webhook

After you delete a webhook from a gate, you will no longer receive notifications for the selected status change for the gate.

  1. On the Value Streams screen, select the value stream that contains the webhook you want to delete.

  2. Select the gate that contains the webhook you want to delete.

  3. In the right panel, scroll to the bottom of the panel, and then select the webhook you want to delete.

  4. Click Delete.

  5. Click OK to confirm that you want to delete the webhook.