diff --git a/content/developers/webhooks-and-events/configuring-your-server-to-receive-payloads.md b/content/developers/webhooks-and-events/configuring-your-server-to-receive-payloads.md index 42464d48ef..3b00914811 100644 --- a/content/developers/webhooks-and-events/configuring-your-server-to-receive-payloads.md +++ b/content/developers/webhooks-and-events/configuring-your-server-to-receive-payloads.md @@ -16,37 +16,17 @@ topics: Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server to handle incoming payloads. -Recall that we specifically set our webhook URL to `http://localhost:4567/payload`. -Since we're developing locally, we'll need to expose our local development environment -to the Internet, so that GitHub can send out messages, and our local server can -process them. +{% note %} -Note: you can download the complete source code for this project +**Note:** You can download the complete source code for this project [from the platform-samples repo][platform samples]. -### Using ngrok - -First, we'll install a program to expose our local host to the Internet. We'll use -ngrok to do this. [ngrok is a free download](https://ngrok.com/download) available -for all major operating systems. - -When you're done with that, you can expose your localhost by running `./ngrok http 4567` -on the command line. You should see a line that looks something like this: - -```shell -$ Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567 -``` - -Copy that funky `*.ngrok.io` URL! We're now going to go *back* to the Payload -URL and pasting this server into that field. It should look something like `http://7e9ea9dc.ngrok.io/payload`. - -By doing this, we've set ourselves up to expose our localhost at path `/payload` -to the Internet. +{% endnote %} ### Writing the server -Now comes the fun part! We want our server to listen to `POST` requests, at `/payload`, -because that's where we told GitHub our webhook URL was. Since ngrok is exposing +We want our server to listen to `POST` requests, at `/payload`, +because that's where we told GitHub our webhook URL was. Because we're using ngrok to expose our local environment, we don't need to set up a real server somewhere online, and can happily test out our code locally. @@ -68,7 +48,7 @@ end Start this server up. Since we set up our webhook to listen to events dealing with `Issues`, go ahead -and create a new Issue on the repository you're testing with. Once you create +and create a new issue on the repository you're testing with. Once you create it, switch back to your terminal. You should see something like this in your output: ```shell diff --git a/content/developers/webhooks-and-events/creating-webhooks.md b/content/developers/webhooks-and-events/creating-webhooks.md index ab6e95e7bb..6cfa64bef6 100644 --- a/content/developers/webhooks-and-events/creating-webhooks.md +++ b/content/developers/webhooks-and-events/creating-webhooks.md @@ -13,14 +13,26 @@ topics: -Now that we understand [the basics of webhooks][webhooks-overview], 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. +Now that we understand [the basics of webhooks][webhooks-overview], 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 how you want your webhook to behave through {% data variables.product.product_name %}--what events should it listen to. After that, you'll set up your server to receive and manage the payload. +Creating a webhook is a two-step process. You'll first need to set up how you want your webhook to behave through {% data variables.product.product_name %}: what events should it listen to. After that, you'll set up your server to receive and manage the payload. {% data reusables.webhooks.webhooks-rest-api-links %} -### Setting up a Webhook +### Exposing localhost to the internet + +For the purposes of this tutorial, we're going to use a local server to receive messages from {% data variables.product.prodname_dotcom %}. So, first of all, we need to expose our local development environment to the internet. 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](https://ngrok.com/download). + +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: + +```shell +$ 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. @@ -34,9 +46,9 @@ Webhooks require a few configuration options before you can make use of them. We {% data reusables.webhooks.payload_url %} -Since we're developing locally for our tutorial, let's set it to `http://localhost:4567/payload`. We'll explain why in the [Configuring Your Server](/webhooks/configuring/) docs. +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 +### Content type {% data reusables.webhooks.content_type %} For this tutorial, the default content type of `application/json` is fine. @@ -44,7 +56,7 @@ Since we're developing locally for our tutorial, let's set it to `http://localho {% data reusables.webhooks.secret %} -### SSL Verification +### SSL verification {% data reusables.webhooks.webhooks_ssl %} @@ -58,11 +70,13 @@ Events are at the core of webhooks. These webhooks fire whenever a certain actio A full list of webhook events, and when they execute, can be found in [the webhooks API][hooks-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. +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**. Phew! Now that you created the webhook, it's time to set up our local server to test the webhook. Head on over to [Configuring Your Server](/webhooks/configuring/) to learn how to do that. +When you're finished, click **Add webhook**. -#### Wildcard Event +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](/webhooks/configuring/) 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.