Demo Notifications from Webhooks

Learn how to build and configure webhooks in Azure DevOps to automate workflows and integrate with external services. This guide demonstrates setting up a webhook that triggers on build completion, sending real-time notifications and payloads to your designated endpoint. By the end, you'll understand how to integrate webhooks with Azure DevOps and inspect the JSON payloads they send.

Let's dive in.

What Is a Webhook?

A webhook is an efficient method for one application to send real-time data to another service whenever a specific event occurs. Instead of continuously polling for updates, webhooks automatically push relevant data to a preconfigured URL endpoint.

In Azure DevOps, webhooks can be set up to notify external systems when events occur—such as a code push, pull request merge, or a successful build. In this tutorial, we focus on triggering webhooks when a build completes successfully.

Configuring the Webhook in Azure DevOps

In the TestWeb project within Azure DevOps, pipelines are already configured and operational on an ASP.NET Web API. The goal is to receive a notification every time the pipeline builds successfully.

1. Navigate to the lower left-hand corner of Azure DevOps and click on Project Settings.
2. Select Service Hooks.
3. Since no subscriptions are configured yet, click to create a new subscription.

A wide range of services can be integrated, such as Jenkins, Azure App Services, Microsoft Teams, Trello, and more. This integration is especially useful for sending real-time notifications to team channels like Microsoft Teams.

For this exercise, select Webhooks and click Next.

Configuring Events and Settings

Set up the event trigger as Build Completed. In the dropdown menu, select your pipeline (TestWeb) and choose Succeeded as the build status. This ensures that the webhook is triggered only when a build is successful.

Defining the Webhook Destination

Next, configure the destination of your webhook notifications. Webhooks offer the flexibility to point to any URL endpoint—even custom services hosted outside Azure. In this example, we are using RequestBin to inspect the payload sent by the webhook.

To test this setup, copy the RequestBin endpoint URL and execute the following command in your terminal:

curl -d '{ "name": "Yoda" }' \
-H "Content-Type: application/json" \
https://enlxm78wgqdmb.x.pipedream.net/

You can also set up authentication by including basic authentication credentials or custom HTTP headers. Be cautious, as these credentials could be exposed if not managed properly. Additionally, choose the level of resource detail to include in the notification payload: minimal, all, or none. Selecting all will include comprehensive details such as subscription ID, event type, build details, and project information.

Examining the Webhook Payload

After completing the configuration and testing, when a build finishes successfully, a detailed JSON payload similar to the example below is generated:

{
  "root": {
    "subscriptionId": "00000000-0000-0000-0000-000000000000",
    "notificationId": 7,
    "id": "d6ac459c-1b83-44f5-95b5-b5f3d6b672ea",
    "eventType": "build.complete",
    "publisher": "tfs",
    "message": {
      "text": "Build 20150407.2 succeeded",
      "html": "Build <a href=\"https://fabrikam-fiber-inc.visualstudio.com/web/build.aspx?pguid=5023c10b-bef3-41c3-bf53-686c4e340e9e&buildId=1&vsft=35%3f\">20150407.2</a> succeeded",
      "markdown": "Build [20150407.2](https://fabrikam-fiber-inc.visualstudio.com/web/build.aspx?pguid=5023c10b-bef3-41c3-bf53-686c4e340e9e&buildId=1&vsft=35%3f) succeeded"
    },
    "detailedMessage": {
      "text": "Build 20150407.2 succeeded",
      "html": "Build <a href=\"https://fabrikam-fiber-inc.visualstudio.com/web/build.aspx?pguid=5023c10b-bef3-41c3-bf53-686c4e340e9e&buildId=1&vsft=35%3f\">20150407.2</a> succeeded",
      "markdown": "Build [20150407.2](https://fabrikam-fiber-inc.visualstudio.com/web/build.aspx?pguid=5023c10b-bef3-41c3-bf53-686c4e340e9e&buildId=1&vsft=35%3f) succeeded"
    },
    "resource": {
      "links": {
        "web": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/717777fbc-1cf2-4bd1-9540-128c17f766/__/apis/build/Builds/1"
      },
      "id": 1,
      "buildNumber": "20150407.2",
      "status": "completed",
      "queueTime": "2014-04-07T17:22:16.222Z",
      "startTime": "2014-04-07T17:21:20.763574Z",
      "finishTime": "2014-04-07T17:22:16.222Z",
      "uri": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/717777fbc-1cf2-4bd1-9540-128c17f766/_apis/build/Definitions/1",
      "definition": {
        "id": 1,
        "name": "CustomAddressModule",
        "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/717777fbc-1cf2-4bd1-9540-128c17f766/_apis/build/Definitions/1"
      },
      "project": {
        "id": "717777fbc-1cf2-4bd1-9540-128c17f766",
        "name": "Git"
      }
    }
  }
}

Your application can then consume the portions of the payload that are relevant to your use case.

Another sample payload with minimal resource details might look like this:

{
  "logs": {
    "type": "Container",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/71777fbc-1cf2-4bd1-9540-128c1c71f766/_apis/builds/1/logs"
  },
  "repository": {
    "id": "47de0965-dad2-4d32-9812-ase598179",
    "name": "TfGit",
    "type": "JamaHartehntUserBranch",
    "url": "https://fabrikam-fiber-inc.visualstudio.com/DefaultCollection/_apis/git/71777fbc-1cf2-4bd1-9540-128c1c71f766",
    "clean": null,
    "checkoutSubmodules": false
  },
  "triggeredByBuild": null,
  "appendCommitMessagesToRunName": true,
  "resourceVersion": "2.0",
  "resourceContainers": {
    "collection": {
      "id": "c12de0eb-3512-443b-9f9c-c52bca50142c"
    },
    "account": {
      "id": "F84AEC47-9d9b-4511-8281-B63f4ea94f"
    },
    "project": {
      "id": "Debf9317-8678-42d4-a549-6280a7a878f"
    }
  },
  "createdDate": "2024-09-18T03:54:01.8279054Z"
}

Testing the Webhook

After configuring the webhook, test it by sending another HTTP POST request with a different sample payload. Run the following command in your terminal:

curl -d '{ "name": "Han Solo" }' \
-H "Content-Type: application/json" \
https://enkxm78wgdqmb.x.pipedream.net/

Even with minimal settings, a substantial amount of data is transmitted in the payload. Once you have verified the output, click Finish in Azure DevOps.

After finishing, the new webhook configuration will appear in your Service Hooks settings:

Running the Pipeline

Switch back to your pipelines and run the TestWeb pipeline. When the build completes successfully, you will receive a notification in RequestBin. The real-time POST request will include HTTP headers and JSON payload data confirming the build status.

The pipeline details may look similar to the following:

Job
  Pool: KodnikCloudCustomer
  Image: windows-latest
  Agent: KodnikCloudAgent21
  Started: Just now
  Duration: 22s
  
  # Job preparation parameters

With this configuration, every successful build automatically triggers an HTTP POST to your specified endpoint. If you ever need to update the webhook settings—for example, to trigger notifications on pull request events or adjust authentication settings—you can modify these options under Project Settings > Service Hooks.

Thank you for reading this guide. Stay tuned for more insights and advanced integrations with Azure DevOps webhooks.