jprdonnelly/docs
1
0
Fork 0
mirror of synced 2026-01-18 15:02:54 -05:00
Code Issues Projects Releases Wiki Activity

Merge pull request #28150 from github/repo-sync

Browse Source 
Repo sync
This commit is contained in:
docs-bot
2023-09-11 14:00:02 -07:00
committed by GitHub
parent 6be4e81a44 40fa8fcfe0
commit 006d9bec7d
10 changed files with 250 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
content/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api.md
View File

@@ -19,7 +19,7 @@ shortTitle: Webhook events
## About webhooks and {% data variables.product.prodname_marketplace %}
Webhooks `POST` requests have special headers. See "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#delivery-headers)" for more details. GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub.
Webhooks `POST` requests have special headers. See "[AUTOTITLE](/webhooks-and-events/webhooks/webhook-events-and-payloads#delivery-headers)" for more details. GitHub doesn't resend failed delivery attempts. Ensure your app can receive all webhook payloads sent by GitHub. For information about how to create {% data variables.product.prodname_marketplace %} webhooks, see "[AUTOTITLE](/webhooks/creating-webhooks)."
Cancellations and downgrades take effect on the first day of the next billing cycle. Events for downgrades and cancellations are sent when the new plan takes effect at the beginning of the next billing cycle. Events for new purchases and upgrades begin immediately. Use the `effective_date` in the webhook payload to determine when a change will begin.

2
content/webhooks/using-webhooks/best-practices-for-using-webhooks.md
View File

@@ -13,7 +13,7 @@ topics:
## Subscribe to the minimum number of events
You should only subscribe to the webhook events that you need. This will reduce the amount of work your server needs to do.
You should only subscribe to the webhook events that you need. This will reduce the amount of work your server needs to do. For more information, see "[AUTOTITLE](/webhooks/creating-webhooks)."
## Use a webhook secret

76
content/webhooks/using-webhooks/configuring-your-server-to-receive-payloads.md
View File

@@ -1,76 +0,0 @@
---
title: Configuring your server to receive payloads
intro: Learn to set up a server to manage incoming webhook payloads.
redirect_from:
- /webhooks/configuring
- /developers/webhooks-and-events/configuring-your-server-to-receive-payloads
- /developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads
- /webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads
- /webhooks/webhooks/configuring-your-server-to-receive-payloads
- /webhooks/configuring-your-server-to-receive-payloads
versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Webhooks
shortTitle: Configure server for webhooks
---
Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server
to handle incoming payloads.
{% note %}
**Note:** You can download the complete source code for this project
[from the platform-samples repo][platform samples].
{% endnote %}
## Writing the server
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.
Let's set up a little Sinatra app to do something with the information. Our initial
setup might look something like this:
``` ruby
require 'sinatra'
require 'json'
post '/payload' do
push = JSON.parse(request.body.read)
puts "I got some JSON: #{push.inspect}"
end
```
(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].)
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
it, switch back to your terminal. You should see something like this in your output:
```shell
$ ~/Developer/platform-samples/hooks/ruby/configuring-your-server $ ruby server.rb
> == Sinatra/1.4.4 has taken the stage on 4567 for development with backup from Thin
> >> Thin web server (v1.5.1 codename Straight Razor)
> >> Maximum connections set to 1024
> >> Listening on localhost:4567, CTRL+C to stop
> I got some JSON: {"action"=>"opened", "issue"=>{"url"=>"...
```
Success! You've successfully configured your server to listen to webhooks. Your
server can now process this information any way you see fit. For example, if you
were setting up a "real" web application, you might want to log some of the JSON
output to a database.
For additional information on working with webhooks for fun and profit, head on
over to the [Testing Webhooks](/webhooks-and-events/webhooks/testing-webhooks) guide.
[platform samples]: https://github.com/github/platform-samples/tree/master/hooks/ruby/configuring-your-server
[Sinatra]: http://www.sinatrarb.com/

137
content/webhooks/using-webhooks/creating-webhooks.md
View File

@@ -1,6 +1,6 @@
---
title: Creating webhooks
intro: 'Learn to build a webhook, choosing the events your webhook will listen for on {% data variables.product.prodname_dotcom %} and how to set up a server to receive and manage the webhook payload.'
intro: 'You can create webhooks to subscribe to specific events that occur on {% data variables.product.prodname_dotcom %}.'
redirect_from:
- /webhooks/creating
- /developers/webhooks-and-events/creating-webhooks
@@ -16,94 +16,89 @@ versions:
topics:
- Webhooks
---
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 what events your webhook should listen to. After that, you'll set up your server to receive and manage the payload.
## About creating webhooks
{% data reusables.webhooks.webhooks-rest-api-links %}
{% ifversion fpt %}You can create webhooks to subscribe to specific events on {% data variables.product.prodname_dotcom %} that occur in a repository, organization, {% data variables.product.prodname_marketplace %} account, or {% data variables.product.prodname_sponsors %} account. You can also set up a {% data variables.product.prodname_github_app %} to recieve webhooks when specific events occur on {% data variables.product.prodname_dotcom %}.{% endif %}
## Exposing localhost to the internet
{% ifversion ghec %}You can create webhooks to subscribe to specific events on {% data variables.product.prodname_dotcom %} that occur in a repository, organization, {% data variables.product.prodname_enterprise %}, {% data variables.product.prodname_marketplace %} account, or {% data variables.product.prodname_sponsors %} account. You can also set up your {% data variables.product.prodname_github_app %} to recieve webhooks when specific events occur on {% data variables.product.prodname_dotcom %}.{% endif %}
For the purposes of this tutorial, we're going to use a local server to receive webhook events from {% data variables.product.prodname_dotcom %}.
{% ifversion ghes or ghae %}You can create webhooks to subscribe to specific events on {% data variables.product.prodname_dotcom %} that occur in a repository, organization, or {% data variables.product.prodname_enterprise %}. You can also set up your {% data variables.product.prodname_github_app %} to recieve webhooks when specific events occur on {% data variables.product.prodname_dotcom %}.{% endif %}
First of all, we need to expose our local development environment to the internet so {% data variables.product.prodname_dotcom %} can deliver events. We'll use [`ngrok`](https://ngrok.com) to do this.
For more information about the different types of webhooks, see "[AUTOTITLE](/webhooks/about-webhooks)." For a complete list of webhook events, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads)."
{% ifversion cli-webhook-forwarding %}
{% note %}
## Creating a repository webhook
**Note:** Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)."
You can create a webhook to subscribe to events that occur in a specific repository. You must be a repository owner or have admin access in the repository to create webhooks in that repository.
You can use the {% data variables.product.prodname_dotcom %} web interface or the REST API to create a repository webhook. For more information about using the REST API to create a repository webhook, see "[AUTOTITLE](/rest/webhooks/repos#create-a-repository-webhook)."
{% data reusables.repositories.navigate-to-repo %}
{% data reusables.repositories.sidebar-settings %}
{% data reusables.webhooks.sidebar_webhooks %}
{% data reusables.webhooks.add_webhook_button %}
1. Under "Payload URL", type the URL where you'd like to receive payloads.
{% data reusables.webhooks.content_type_and_secret %}
1. Under "Which events would you like to trigger this webhook?", select the webhook events that you want to receive. You should only subscribe to the webhook events that you need.
1. If you chose **Let me select individual events**, select the events that you want to trigger the webhook.
1. To make the webhook active immediately after adding the configuration, select **Active**.
{% data reusables.webhooks.add_webhook_button %}
After you create a new webhook, {% data variables.product.prodname_dotcom %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads#ping)."
## Creating an organization webhook
You can create a webhook to subscribe to events that occur in a specific organization. You must be an organization owner to create webhooks in that organization.
You can use the {% data variables.product.prodname_dotcom %} web interface or the REST API to create an organization webhook. For more information about using the REST API to create an organization webhook, see "[AUTOTITLE](/rest/orgs/webhooks#create-an-organization-webhook)."
1. In the upper-right corner of any page on {% data variables.location.product_location %}, click your profile photo.
1. Click **Your organizations**.
1. To the right of the organization, click **Settings**.
{% data reusables.webhooks.sidebar_webhooks %}
{% data reusables.webhooks.add_webhook_button %}
1. Under "Payload URL", type the URL where you'd like to receive payloads.
{% data reusables.webhooks.content_type_and_secret %}
1. Under "Which events would you like to trigger this webhook?", select the types of webhooks you'd like to recieve. You should only subscribe to the webhook events that you need.
1. If you chose **Let me select individual events**, select the events that will trigger the webhook.
1. To make the webhook active immediately after adding the configuration, select **Active**.
1. Click **Add webhook**.
After you create a new webhook, {% data variables.product.prodname_dotcom %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads#ping)."
{% ifversion ghes or ghae or ghec %}
## Creating a global webhook for a {% data variables.product.prodname_enterprise %}
Enterprise owners can create a global webhook to subscribe to events that occur within their enterprise. For more information, see "[AUTOTITLE](/admin/monitoring-activity-in-your-enterprise/exploring-user-activity-in-your-enterprise/managing-global-webhooks)."
{% endnote %}
{% endif %}
`ngrok` is available, free of charge, for all major operating systems. For more information, see [the `ngrok` download page](https://ngrok.com/download).
{% ifversion fpt or ghec %}
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:
## Creating a {% data variables.product.prodname_marketplace %} webhook
```shell
Forwarding http://7e9ea9dc.ngrok.io -> 127.0.0.1:4567
```
You can create a webhook to subscribe to events relating to an app that you published in {% data variables.product.prodname_marketplace %}. Only the owner of the app, or an app manager for the organization that owns the app, can create a {% data variables.product.prodname_marketplace %} webhook. For more information, see "[AUTOTITLE](/apps/publishing-apps-to-github-marketplace/using-the-github-marketplace-api-in-your-app/webhook-events-for-the-github-marketplace-api)."
Make a note of the `*.ngrok.io` URL. We'll use it to set up our webhook.
1. Navigate to your [{% data variables.product.prodname_marketplace %} listing page](https://github.com/marketplace/manage).
1. Next to the {% data variables.product.prodname_marketplace %} listing that you want to view webhook deliveries for, click **Manage listing**.
1. In the sidebar, click **Webhook**.
1. Under "Payload URL", type the URL where you'd like to receive payloads.
{% data reusables.webhooks.content_type_and_secret %}
1. To make the webhook active immediately after adding the configuration, select **Active**.
1. Click **Create webhook**.
## Setting up a webhook
After you create a new webhook, {% data variables.product.prodname_dotcom %} will send you a simple `ping` event to let you know you've set up the webhook correctly. For more information, see "[AUTOTITLE](/webhooks/webhook-events-and-payloads#ping)."
You can install webhooks on an organization or on a specific repository.
## Creating a {% data variables.product.prodname_sponsors %} webhook
{% data reusables.organizations.owners-and-admins-can %} manage webhooks for an organization. {% data reusables.organizations.new-org-permissions-more-info %}
You can create a webhook to subscribe to events relating to {% data variables.product.prodname_sponsors %}. Only the owner of the sponsored account can create sponsorship webhooks for that account. For more information, see "[AUTOTITLE](/sponsors/integrating-with-github-sponsors/configuring-webhooks-for-events-in-your-sponsored-account)."
To set up a webhook, go to the settings page of your repository or organization. From there, click **Webhooks**, then **Add webhook**.
{% endif %}
Alternatively, you can choose to build and manage a webhook [through the Webhooks API][webhook-api].
## Creating webhooks for a {% data variables.product.prodname_github_app %}
Webhooks require a few configuration options before you can make use of them. We'll go through each of these settings below.
You can subscribe your {% data variables.product.prodname_github_app %} to webhook events to receive notifications whenever certain events occur. For more information, see "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)" and "[AUTOTITLE](/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps)."
## Payload URL
## Further reading
{% data reusables.webhooks.webhooks-ipv6 %}
{% data reusables.webhooks.payload_url %}
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
{% data reusables.webhooks.content_type %} For this tutorial, the default content type of `application/json` is fine.
## Secret
{% data reusables.webhooks.secret %}
## SSL verification
{% data reusables.webhooks.webhooks_ssl %}
## 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][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.
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](/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads) 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.
[webhooks-overview]: /webhooks-and-events/webhooks/about-webhooks
[webhook-api]: /rest/repos#hooks
[hooks-api]: /webhooks-and-events/webhooks/about-webhooks#events
### Ping event
{% data reusables.webhooks.ping_short_desc %}
For more information about the `ping` event webhook payload, see the [`ping`](/webhooks-and-events/webhooks/webhook-events-and-payloads#ping) event.
- "[AUTOTITLE](/webhooks/using-webhooks/handling-webhook-deliveries)"

175
content/webhooks/using-webhooks/handling-webhook-deliveries.md Normal file
View File

@@ -0,0 +1,175 @@
---
title: Handling webhook deliveries
intro: 'Learn how to build a webhook, choose the events your webhook will listen for on {% data variables.product.prodname_dotcom %}, and set up a server to receive and manage the webhook payload.'
redirect_from:
- /webhooks/configuring
- /developers/webhooks-and-events/configuring-your-server-to-receive-payloads
- /developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads
- /webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads
- /webhooks/webhooks/configuring-your-server-to-receive-payloads
- /webhooks/configuring-your-server-to-receive-payloads
- /webhooks/using-webhooks/configuring-your-server-to-receive-payloads
versions:
fpt: '*'
ghes: '*'
ghae: '*'
ghec: '*'
topics:
- Webhooks
---
## Introduction
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. Then we'll set up a server to manage the incoming webhook payloads.
## Creating a webhook
Creating a webhook is a two-step process. You'll first need to set up the events your webhook should listen to. After that, you'll set up your server to receive and manage the payload.
{% data reusables.webhooks.webhooks-rest-api-links %}
### Exposing localhost to the internet
For the purposes of this tutorial, we're going to use a local server to receive webhook events from {% data variables.product.prodname_dotcom %}.
First of all, we need to expose our local development environment to the internet so {% data variables.product.prodname_dotcom %} can deliver events. We'll use [`ngrok`](https://ngrok.com) to do this.
{% ifversion cli-webhook-forwarding %}
{% note %}
**Note:** Alternatively, you can use webhook forwarding to set up your local environment to receive webhooks. For more information, see "[AUTOTITLE](/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)."
{% endnote %}
{% endif %}
`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.
{% data reusables.organizations.owners-and-admins-can %} manage webhooks for an organization. {% data reusables.organizations.new-org-permissions-more-info %}
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][webhook-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
{% data reusables.webhooks.webhooks-ipv6 %}
{% data reusables.webhooks.payload_url %}
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
{% data reusables.webhooks.content_type %} For this tutorial, the default content type of `application/json` is fine.
### Secret
{% data reusables.webhooks.secret %}
### SSL verification
{% data reusables.webhooks.webhooks_ssl %}
### 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][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.
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](/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads) 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.
[webhooks-overview]: /webhooks-and-events/webhooks/about-webhooks
[webhook-api]: /rest/repos#hooks
[hooks-api]: /webhooks-and-events/webhooks/about-webhooks#events
#### Ping event
{% data reusables.webhooks.ping_short_desc %}
For more information about the `ping` event webhook payload, see the [`ping`](/webhooks-and-events/webhooks/webhook-events-and-payloads#ping) event.
## Configuring your server to receive payloads
Now that our webhook is ready to deliver messages, we'll set up a basic Sinatra server
to handle incoming payloads.
{% note %}
**Note:** You can download the complete source code for this project
[from the platform-samples repo][platform samples].
{% endnote %}
### Writing the server
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.
Let's set up a little Sinatra app to do something with the information. Our initial
setup might look something like this:
``` ruby
require 'sinatra'
require 'json'
post '/payload' do
push = JSON.parse(request.body.read)
puts "I got some JSON: #{push.inspect}"
end
```
(If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].)
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
it, switch back to your terminal. You should see something like this in your output:
```shell
$ ~/Developer/platform-samples/hooks/ruby/configuring-your-server $ ruby server.rb
> == Sinatra/1.4.4 has taken the stage on 4567 for development with backup from Thin
> >> Thin web server (v1.5.1 codename Straight Razor)
> >> Maximum connections set to 1024
> >> Listening on localhost:4567, CTRL+C to stop
> I got some JSON: {"action"=>"opened", "issue"=>{"url"=>"...
```
Success! You've successfully configured your server to listen to webhooks. Your
server can now process this information any way you see fit. For example, if you
were setting up a "real" web application, you might want to log some of the JSON
output to a database.
For additional information on working with webhooks for fun and profit, head on
over to the [Testing Webhooks](/webhooks-and-events/webhooks/testing-webhooks) guide.
[platform samples]: https://github.com/github/platform-samples/tree/master/hooks/ruby/configuring-your-server
[Sinatra]: http://www.sinatrarb.com/

3
content/webhooks/using-webhooks/index.md
View File

@@ -10,8 +10,7 @@ topics:
- Webhooks
children:
- /creating-webhooks
- /configuring-your-server-to-receive-payloads
- /handling-webhook-deliveries
- /securing-your-webhooks
- /best-practices-for-using-webhooks
---

1
data/reusables/repositories/sidebar-settings.md
View File

@@ -1,3 +1,2 @@
1. Under your repository name, click {% octicon "gear" aria-hidden="true" %} **Settings**. If you cannot see the "Settings" tab, select the **{% octicon "kebab-horizontal" aria-label="More" %}** dropdown menu, then click **Settings**.
![Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.](/assets/images/help/repository/repo-actions-settings.png)

1
data/reusables/webhooks/add_webhook_button.md Normal file
View File

@@ -0,0 +1 @@
1. Click **Add webhook**.

4
data/reusables/webhooks/content_type_and_secret.md Normal file
View File

@@ -0,0 +1,4 @@
1. Optionally, select the **Content type** drop-down menu, and click a data format to receive the webhook payload in.
- **application/json** will deliver the JSON payload directly as the body of the `POST` request.
- **application/x-www-form-urlencoded** will send the JSON payload as a form parameter called `payload`.
1. Optionally, under "Secret", type a string to use as a `secret` key. You should choose a random string of text with high entropy. You can use the webhook secret to limit incoming requests to only those originating from {% data variables.product.prodname_dotcom %}. For more information, see "[AUTOTITLE](/webhooks/using-webhooks/securing-your-webhooks)."

1
data/reusables/webhooks/sidebar_webhooks.md Normal file
View File

@@ -0,0 +1 @@
1. In the left sidebar, click **{% octicon "webhook" aria-hidden="true" %} Webhooks**.