Use a webhook as a trigger for Azure Logic Apps and Microsoft Flow

Webhooks are simple HTTP callbacks used to provide event notifications. Azure Logic Apps and Microsoft Flow both allow you to use webhooks as triggers. A logic app or flow listens for this trigger and performs an action whenever the trigger fires. This tutorial demonstrates how to use a webhook as a trigger.

Note

We'll use GitHub as an example of a service that can send notifications via webhooks, but the techniques demonstrated here can be extended to any service that uses webhooks.

Prerequisites

The OpenAPI definition

Webhooks are implemented in Logic Apps and Microsoft Flow as part of a custom connector, so you need to provide an OpenAPI definition that defines the shape of the webhook. If you want to created a trigger but you don't have an OpenAPI definition, you can use the triggers UI in the custom connector wizard to define webhook triggers.

The OpenAPI contains definition contains three parts that are critical to making the webhook work:

  • Creating the webhook
  • Defining the incoming hook request from the API (in this case, GitHub)
  • Deleting the webhook

Creating the webhook

The webhook is created on the GitHub side by an HTTP POST to /repos/{owner}/{repo}/hooks. When a new logic app or flow is created, it posts to this URL using the trigger defined in the OpenAPI definition. It also posts to the URL if the trigger is modified. In the sample below, the post property contains the schema of the request that is posted to GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
    "description": "Details for Webhook",
    "schema": {
        "$ref": "#/definitions/WebhookPushResponse"
    }
    },
    "post": {
    "description": "Creates a Github webhook",
    "summary": "Triggers when a PUSH event occurs",
    "operationId": "webhook-trigger",
    "x-ms-trigger": "single",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "Request body of webhook",
        "in": "body",
        "description": "This is the request body of the Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookRequestBody"
        }
        }
    ],
    "responses": {
        "201": {
        "description": "Created",
        "schema": {
            "$ref": "#/definitions/WebhookCreationResponse"
        }
        }
    }
    }
},

Important

The "x-ms-trigger": "single" property is a schema extension that tells Logic Apps and Microsoft Flow to display this webhook in the list of available triggers in the designer, so be sure to include it.

Defining the incoming hook request from the API

The shape of the incoming hook request (the notification from GitHub to Logic Apps or Microsoft Flow) is defined in the custom x-ms-notification-content property, as shown in the sample above. It doesn't need to contain the entire contents of the request, just the portions you want to use in your logic app or flow.

Deleting the webhook

The OpenAPI definition must include a definition for how to delete the webhook. Logic Apps and Microsoft Flow attempt to delete the webhook if you update the trigger, and if you delete the logic app or flow.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
    "description": "Deletes a Github webhook",
    "operationId": "DeleteTrigger",
    "parameters": [
        {
        "name": "owner",
        "in": "path",
        "description": "Name of the owner of targeted repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "repo",
        "in": "path",
        "description": "Name of the repository",
        "required": true,
        "type": "string"
        },
        {
        "name": "hook_Id",
        "in": "path",
        "description": "ID of the Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

Important

In order for Logic Apps or Microsoft Flow to delete a webhook, the API must include a Location HTTP header in the 201 response at the time the webhook is created. The Location header should contain the path to the webhook that is used with the HTTP DELETE. For example, the Location included with GitHub's response follows this format: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Enable authentication in GitHub

The API that sends the webhook request to Logic Apps or Microsoft Flow typically uses some form of authentication, and GitHub is no exception. GitHub supports several types of authentication; we'll use GitHub personal access tokens for this tutorial.

  1. Navigate to GitHub and sign in if you haven't already.

  2. In the upper right, select your profile picture, and then, in the menu, choose Settings.

    Settings

  3. In the menu on the left, choose Developer settings, then choose Personal access tokens.

  4. Choose the Generate new token button, then confirm your password if requested.

    Generate new token

  5. In the Token description box, enter a description.

  6. Select the admin:repo_hook checkbox.

    admin:repo_hook

  7. Choose the Generate token button.

  8. Make note of your new token.

    New token

    Important

    You won't be able to access this token again. You should copy and paste it somewhere to use later in the tutorial.

Import the OpenAPI definition

Start by importing the OpenAPI definition for Logic Apps, or for Microsoft Flow.

Import the OpenAPI definition for Logic Apps

  1. Go to the Azure portal, and open the Logic Apps connector you created earlier in Create an Azure Logic Apps custom connector.

  2. In your connector's menu, choose Logic Apps Connector, then choose Edit.

    Edit Logic Apps Connector

  3. Under General, choose Upload an OpenAPI file, then navigate to the OpenAPI file that you downloaded.

    Upload Postman collection

Import the OpenAPI definition for Microsoft Flow

  1. Go to flow.microsoft.com.

  2. In the upper right corner, choose the gear icon, then choose Custom connectors.

    Custom connectors

  3. Choose Create custom connector, then choose Import a Postman collection.

    Create custom connector

  4. Enter a name for the custom connector, then navigate to the OpenAPI file that you downloaded, and choose Connect.

    Upload Postman collection

    Parameter Value
    Custom connector title "GitHubDemo"

Finish creating the custom connector

  1. On the General page, choose Continue.

  2. On the Security page, under Authentication type, select Basic authentication.

  3. In the Basic authentication section, for the label fields, enter the text User name and Password. Note that these are only labels that will be displayed when the trigger is used in a logic app or flow.

    Basic auth

  4. At the top of the wizard, make sure the name is set to "GitHubDemo", then choose Create connector.

You're now ready to use the trigger in a logic app or flow, or you can read on about how to create triggers from the UI.

Create webhook triggers from the UI

In this section, we'll show you how to create a trigger in the UI without having any trigger definitions in your OpenAPI definition. Start with a baseline OpenAPI definition, or start from scratch in the custom connector wizard.

  1. On the General page, make sure you specify a description and URL.

    Parameter Value
    Description "GitHub is a social source code repository."
    URL "api.github.com"
  2. On the Security page, configure basic authentication like you did in the previous section.

  3. On the Definition page, choose + New trigger, and fill out the description for your trigger. In this example, we are creating a trigger that fires when a pull request is made to a repository.

    Create Trigger-1

    Parameter Value
    Summary "Triggers when a pull request is made to a selected repository"
    Description "Triggers when a pull request is made to a selected repository"
    Operation ID "webhook-PR-trigger"
    Visibility "none" (see below for more information)
    Trigger type "Webhook"

    The Visibility property for operations and parameters in a logic app or flow has the following options:

    • none: displayed normally in the logic app or flow
    • advanced: hidden under an additional menu
    • internal: hidden from the user
    • important: always shown to the user first
  4. The Request area displays information based on the HTTP request for the action. Choose Import from sample.

    Definition page - import from sample

  5. Define the request for the webhook trigger, then choose Import. We provide a sample for you to import (below the image). For more information, see the Github API reference. Logic Apps and Microsoft Flow automatically add standard content-type and security headers, so you don’t need to define those while importing from a sample.

    Create Trigger-2

    Parameter Value
    Verb "POST"
    URL "https://api.github.com/repos/{owner}/{repo}/hooks"
    Body See below
    {
      "name": "web",
      "active": true,
      "events": [
        "pull_request"
      ],
      "config": {
        "url": "http://example.com/webhook"
      }
    }
    
  6. The Response area displays information based on the HTTP response for the action. Choose Add default response.

    Definition page - response

  7. Define the response for the webhook trigger, then choose Import. Again, we provide a sample for you to import. For more information, see the Github API reference.

    Create Trigger-3

    {
      "action": "opened",
      "number": 1,
      "pull_request": {
        "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
        "state": "open",
        "locked": false,
        "title": "Update the README with new information",
        "user": {
          "login": "baxterthehacker",
          "type": "User"
        }
      }
    }
    
  8. In the Trigger configuration area, select the parameter that should receive the callback URL value from GitHub. This is the url property in the config object.

    Create Trigger-4

  9. At the top of the wizard, enter a name, then choose Create connector.

Use the webhook as a trigger

Now that we've got everything configured, we can use the webhook in a logic app or flow. Let's create a flow that will send a push notification to the Microsoft Flow mobile app whenever our GitHub repo receives a git push.

  1. In flow.microsoft.com, at the top of the page, choose My flows.

  2. Choose Create from blank, then on the next page, choose Search hundreds of connectors and triggers.

    Search connectors

  3. In the designer for Microsoft Flow, search for the custom connector we registered earlier.

    New trigger

    Choose the item in the list to use it as a trigger.

  4. Since this is the first time we've used this custom connector, we have to connect to it. Enter connection information, then choose Create.

    New connection

    Parameter Value
    Connection name A descriptive name
    User name Your GitHub username
    Password The personal access token you created earlier
  5. Enter details about the repo we want to monitor. You might recognize the fields from the WebhookRequestBody object in the OpenAPI file.

    Repo info

    Parameter Value
    owner The owner of the repo to monitor
    repo The repo to monitor

    Important

    You should use a repo that your account has rights to. The easiest way to do this would be to use your own repo.

  6. Choose + New step, and then choose Add an action.

  7. Search for and select the Push notification action.

    Push notification

  8. Enter some text in the Text field and the other fields, using values from the dynamic content dialog box. Note that these values come from the WebhookPushResponse object in the OpenAPI file.

    Push notification details

    Parameter Value
    Connection name A descriptive name
    User name Your GitHub username
    Password The personal access token you created earlier
  9. At the top of the page, give the flow a name and choose Create flow.

    Flow name

Verification and troubleshooting

To verify everything is set up correctly, choose My flows, then choose the information icon next to the new flow to view the run history:

  • You should already see at least one "Succeeded" run from the webhook creation. This indicates that the webhook was created successfully on the GitHub side.

  • If the run failed, you can drill into the run details to see why it failed. If the failure was due to a "404 Not Found" response, it's likely your GitHub account doesn't have the correct permissions to create a webhook on the repo you used.

Summary

If everything is correctly configured, you will now receive push notifications in the Microsoft Flow mobile app whenever a git push occurs on the GitHub repository you selected. Using the process above, you can use any webhook-capable service as a trigger in your flows.

Next steps