Creating webhooks

Now that we understand the basics of webhooks, let's go through the process of building out our own webhook-powered integration. In this tutorial, we'll create a repository webhook that will be responsible for listing out how popular our repository is, based on the number of issues it receives per day.

Creating a webhook is a two-step process. You'll first need to set up what events your webhook should listen to. After that, you'll set up your server to receive and manage the payload.

You can use the REST API to manage repository, organization, and app webhooks. You can list webhook deliveries for a webhook, or get and redeliver an individual delivery for a webhook, which can be integrated into an external app or service. You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:

• Repository Webhooks
• Organization Webhooks
• GitHub App Webhooks

Exposing localhost to the internet

For the purposes of this tutorial, we're going to use a local server to receive webhook events from GitHub.

First of all, we need to expose our local development environment to the internet so GitHub can deliver events. We'll use ngrok to do this.

ngrok is available, free of charge, for all major operating systems. For more information, see the ngrok download page.

After installing ngrok, you can expose your localhost by running ./ngrok http 4567 on the command line. 4567 is the port number on which our server will listen for messages. You should see a line that looks something like this:

Forwarding  http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567

Make a note of the *.ngrok.io URL. We'll use it to set up our webhook.

Setting up a webhook

You can install webhooks on an organization or on a specific repository.

Only members with owner privileges for an organization or admin privileges for a repository can manage webhooks for an organization. For more information, see "Roles in an organization."

To set up a webhook, go to the settings page of your repository or organization. From there, click Webhooks, then Add webhook.

Alternatively, you can choose to build and manage a webhook through the Webhooks API.

Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.

Payload URL

The payload URL is the URL of the server that will receive the webhook POST requests.

Since we're developing locally for our tutorial, we'll set it to the *.ngrok.io URL, followed by /payload. For example, http://7e9ea9dc.ngrok.io/payload.

Content type

Webhooks can be delivered using different content types:

• The application/json content type will deliver the JSON payload directly as the body of the POST request.
• The application/x-www-form-urlencoded content type will send the JSON payload as a form parameter called payload.

Choose the one that best fits your needs. For this tutorial, the default content type of application/json is fine.

Secret

Setting a webhook secret allows you to ensure that POST requests sent to the payload URL are from GitHub Enterprise Server. When you set a secret, you'll receive the X-Hub-Signature and X-Hub-Signature-256 headers in the webhook POST request. For more information on how to use a secret with a signature header to secure your webhook payloads, see "Securing your webhooks."

SSL verification

If your "Payload URL" is a secure site (HTTPS), you will have the option to configure the SSL verification settings. If your "Payload URL" is not secure (HTTP), GitHub will not display this option. By default, GitHub verifies the SSL certificate of your website when delivering webhook payloads. SSL verification helps ensure that hook payloads are delivered to your URL endpoint securely. You have the option to disable SSL, but we recommend keeping Enable SSL verification selected.

Active

By default, webhook deliveries are "Active." You can choose to disable the delivery of webhook payloads by deselecting "Active."

Events

Events are at the core of webhooks. These webhooks fire whenever a certain action is taken on the repository, which your server's payload URL intercepts and acts upon.

A full list of webhook events, and when they execute, can be found in the webhooks API reference.

Since our webhook is dealing with issues in a repository, we'll click Let me select individual events and then Issues. Make sure you select Active to receive issue events for triggered webhooks. You can also select all events using the default option.

When you're finished, click Add webhook.

Now that you've created the webhook, it's time to set up our local server to test the webhook. Head on over to Configuring Your Server to learn how to do that.

Wildcard event

To configure a webhook for all events, use the wildcard (*) character to specify the webhook events. When you add the wildcard event, we'll replace any existing events you have configured with the wildcard event and send you payloads for all supported events. You'll also automatically get any new events we might add in the future.

Ping event

When you create a new webhook, we'll send you a simple ping event to let you know you've set up the webhook correctly. This event isn't stored so it isn't retrievable via the Events API endpoint.

For more information about the ping event webhook payload, see the ping event.