Exercise - Set up a webhook for a GitHub repository

In this exercise, you'll set up a webhook for a GitHub repository. You'll learn how to listen for specific events, (in this case, the Gollum event), and how to make your webhook callback to your function when the event is triggered.

Setup

  1. Using your web browser, sign in to your GitHub account.

  2. Create a new repository by selecting New in the left nav bar, and enter a meaningful name such as LearnWebhookTest.

  3. Select Public to activate your wiki module, and find it in the menu.

  4. Select Create repository. The Quick setup page appears.

  5. Select the creating a new file link.

  6. Select the Wiki tab. A Welcome page appears.

  7. Select Create the first page. The Create new page template appears.

  8. Add some text, and select Save Page.

Add a webhook for the Gollum Event

The Gollum event is the name of the event in GitHub that is fired whenever a page in the repo's wiki is created or updated.

  1. Select Home to return to the home page for your repository.

  2. Select the Settings tab.

  3. Select Webhooks in the navigation panel to the left of the page.

  4. Select Add webhook on the top-right.

  5. Set the payload to the URL for your function app's function from the previous exercise. Remember that it looks similar to this:

    https://<your-functionapp-name>.azurewebsites.net/api/HttpTrigger1?code=aUjXIpqdJ0ZHPQuB0SzFegxGJu0nAXmsQBnmkCpJ6RYxleRaoxJ8cQ==
    
  6. Set the content type to application/json.

  7. In the section Which events would you like to trigger this webhook?, select the radio button labeled Let me select individual events.

  8. Select the Wiki checkbox. Make sure no other check boxes are selected.

  9. At the bottom of the page, ensure Active is checked, and select Add webhook.

  10. Verify that your new webhook appears when the Webhooks page appears.

Test the webhook

  1. In the GitHub portal for your repository, select the Wiki tab.

  2. Select the page that you created earlier.

  3. Select Edit.

  4. In the text area of the page, enter the following text:

    Testing Webhook
    
  5. Select Save Page to save your update.

  6. Select the Settings tab.

  7. Select Webhooks in the navigation panel on the left.

    Note

    The webhook will indicate that the message was not processed correctly; it will generate an HTTP 400 error. The webhook is providing a payload that your function app wasn't expecting, and doesn't include a name parameter. You will learn how to parse the payload for a Gollum event in the next unit.

  8. Select Edit next to your webhook.

  9. Scroll down to the Recent Deliveries section.

  10. Select the latest delivery entry by selecting the ellipsis (...).

    You'll see the Header information, including the Event Type:

    Request URL: https://testwh123456.azurewebsites.net/api/HttpTrigger1?code=aUjXIpqdJ0ZHPQuB0SzFegxGJu0nAXmsQBnmkCpJ6RYxleRaoxJ8cQ%3D%3D
    Request method: POST
    content-type: application/json
    Expect: 
    User-Agent: GitHub-Hookshot/16496cb
    X-GitHub-Delivery: 9ed46280-6ab3-11e9-8a19-f1a14922a239
    X-GitHub-Event: gollum
    

    You'll also see that the payload contains information indicating that your wiki page was edited. The payload contains pages, repository, and sender sections, which should look something like the example shown below:

        "pages": [
            {
                "page_name": "Home",
                "title": "Home",
                "summary": null,
                "action": "edited",
                "sha": "04d012c5f92a95ae3f7721173bf9f2b1b35ea22f",
                "html_url": "https://github.com/.../wiki/Home"
            }
        ],
        "repository" : {
            "id": 176302421,
            "node_id": "MDEwOlJlcG9zaXRvcnkxNzYzMDI0MjE=",
            "name": "tieredstorage",
            ...
        },
        "sender" : {
            ...
        }
    
  11. Select the Response tab.

    You'll see the response message generated by the Azure function. For this example, the body should contain the message. Please pass a name on the query string or in the request body.