Add docs for the new "webhook forwarding" GitHub CLI feature (#32040)

Co-authored-by: Sarah Edwards <skedwards88@github.com>

content/developers/webhooks-and-events/webhooks/configuring-your-server-to-receive-payloads.md

@@ -26,7 +26,7 @@ to handle incoming payloads.
 ## 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
+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.
 

content/developers/webhooks-and-events/webhooks/creating-webhooks.md

@@ -14,16 +14,28 @@ 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.
 
-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 what events you 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 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).
+For the purposes of this tutorial, we're going to use a local server to receive webhook events from {% data variables.product.prodname_dotcom %}. 
 
-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:
+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 "[Receiving webhooks with the GitHub CLI](/developers/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

content/developers/webhooks-and-events/webhooks/index.md

@@ -14,6 +14,7 @@ children:
   - /configuring-your-server-to-receive-payloads
   - /testing-webhooks
   - /securing-your-webhooks
+  - /receiving-webhooks-with-the-github-cli
   - /webhook-events-and-payloads
 ---
 

content/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli.md

@@ -0,0 +1,46 @@
+---
+title: Receiving webhooks with the GitHub CLI
+intro: 'You can use the {% data variables.product.prodname_cli %} to test webhooks in your development environment without the complexity of port forwarding or third-party tools.'
+versions:
+  feature: 'cli-webhook-forwarding'
+topics:
+  - Webhooks
+shortTitle: Receiving webhooks with the GitHub CLI
+---
+## About receiving webhooks with {% data variables.product.prodname_cli %}
+
+{% note %}
+
+**Note**: Receiving webhooks with the {% data variables.product.prodname_cli %} is currently in limited public beta and subject to change. To sign up for the beta, reply to our GitHub Community [discussion](https://github.com/orgs/community/discussions/38261). You may not be added immediately. You will receive an email notification once you have been added to the beta.
+
+{% endnote %}
+
+When you make changes to your integration code, running the code in a local environment lets you test and iterate quickly without deploying the code. You can use {% data variables.product.prodname_cli %} to forward webhooks to your local environment.
+
+{% note %}
+
+**Note:** Webhook forwarding in the {% data variables.product.prodname_cli %} only works with repository and organization webhooks. If you want to test sponsorship, GitHub App, enterprise, or Marketplace webhooks locally, you'll need to do this manually. For more information, see "[Creating webhooks](/developers/webhooks-and-events/webhooks/creating-webhooks)."
+
+{% endnote %}
+
+## Recieving webhooks with {% data variables.product.prodname_cli %}
+
+{% data reusables.cli.cli-learn-more %}
+
+1. To install the {% data variables.product.prodname_cli %} extension to enable webhook forwarding, use the `extension install` subcommand. 
+
+   ```sh
+   gh extension install cli/gh-webhook
+   ```
+
+
+1. Start your application locally, and take a note of the URL where it's expecting to receive webhooks. This guide assumes that your application is listening for webhook events at `http://localhost:3000/webhook`.
+
+1. To set up webhooks to be delivered to your application, run the `webhook forward` subcommand. Replace `REPOSITORY` with the name of your repository. For example, `monalisa/octocat`. Replace `EVENTS` with a comma-separated list of the events that you want to receive. For example, `issues,pull_request`. Replace `URL` with the local URL where your application expects to receive webhooks. For example, `"http://localhost:3000/webhook"`.  To listen for organization webhooks instead of repository webhooks, replace the `--repo` flag with the `--org` flag. For example `--org="octo-org"`.
+
+
+   ```sh
+   gh webhook forward --repo=REPOSITORY --events=EVENTS --url=URL
+   ```
+
+  Leave the command running in the background. It will receive all of the specified events for the specified repository and forward them to your webhook handler running at the specified URL.

content/rest/guides/building-a-ci-server.md

@@ -29,9 +29,17 @@ Our CI system and host server will be figments of our imagination. They could be
 Travis, Jenkins, or something else entirely. The crux of this guide will be setting up
 and configuring the server managing the communication.
 
-If you haven't already, be sure to [download ngrok][ngrok], and learn how
+If you haven't already, [download `ngrok`][ngrok], and learn how
 to [use it][using ngrok]. We find it to be a very useful tool for exposing local
-connections.
+applications to the internet.
+
+{% 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 "[Receiving webhooks with the GitHub CLI](/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)."
+
+{% endnote %}
+{% endif %}
 
 Note: you can download the complete source code for this project
 [from the platform-samples repo][platform samples].
@@ -54,14 +62,14 @@ end
 (If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].)
 
 Start this server up. By default, Sinatra starts on port `4567`, so you'll want
-to configure ngrok to start listening for that, too.
+to configure `ngrok` to start listening for that, too.
 
 In order for this server to work, we'll need to set a repository up with a webhook.
 The webhook should be configured to fire whenever a Pull Request is created, or merged.
 Go ahead and create a repository you're comfortable playing around in. Might we
 suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)?
 After that, you'll create a new webhook in your repository, feeding it the URL
-that ngrok gave you, and choosing `application/x-www-form-urlencoded` as the
+that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the
 content type:
 
 ![A new ngrok URL](/assets/images/webhook_sample_url.png)

content/rest/guides/delivering-deployments.md

@@ -32,9 +32,17 @@ Our CI system and host server will be figments of our imagination. They could be
 Heroku, Amazon, or something else entirely. The crux of this guide will be setting up
 and configuring the server managing the communication.
 
-If you haven't already, be sure to [download ngrok][ngrok], and learn how
+If you haven't already, be sure to [download `ngrok`][ngrok], and learn how
 to [use it][using ngrok]. We find it to be a very useful tool for exposing local
-connections.
+applications to the internet.
+
+{% 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 "[Receiving webhooks with the GitHub CLI](/developers/webhooks-and-events/webhooks/receiving-webhooks-with-the-github-cli)."
+
+{% endnote %}
+{% endif %}
 
 Note: you can download the complete source code for this project
 [from the platform-samples repo][platform samples].
@@ -57,14 +65,14 @@ end
 (If you're unfamiliar with how Sinatra works, we recommend [reading the Sinatra guide][Sinatra].)
 
 Start this server up. By default, Sinatra starts on port `4567`, so you'll want
-to configure ngrok to start listening for that, too.
+to configure `ngrok` to start listening for that, too.
 
 In order for this server to work, we'll need to set a repository up with a webhook.
 The webhook should be configured to fire whenever a pull request is created, or merged.
 Go ahead and create a repository you're comfortable playing around in. Might we
 suggest [@octocat's Spoon/Knife repository](https://github.com/octocat/Spoon-Knife)?
 After that, you'll create a new webhook in your repository, feeding it the URL
-that ngrok gave you, and choosing `application/x-www-form-urlencoded` as the
+that `ngrok` gave you, and choosing `application/x-www-form-urlencoded` as the
 content type:
 
 ![A new ngrok URL](/assets/images/webhook_sample_url.png)

data/features/cli-webhook-forwarding.yml

@@ -0,0 +1,6 @@
+# Issue #8501
+# Webhook forwarding with GitHub CLI
+
+versions:
+  fpt: '*'
+  ghec: '*'