About webhooks and GitHub Apps
Webhooks enable your GitHub App to receive real-time notifications when events happen on GitHub, such as when someone pushes a commit or opens a pull request in a repository that your app can access. For more information about webhooks, see "关于 web 挂钩." For a tutorial that demonstrates how to use webhooks with a GitHub App, see "构建响应 Webhook 事件的 GitHub 应用."
You can configure your GitHub App to receive webhooks for specific events on GitHub and automatically take action on them. For more information about the types of webhooks you can receive, see "Webhook 事件和有效负载."
To receive webhook events in your GitHub App, you must enable webhooks for your GitHub App registration and specify a webhook URL where GitHub will send the webhook payloads.
If your GitHub App does not need to respond to webhooks or will only be used for authentication, you can turn off the webhook function for your GitHub App registration. You do not need to specify a webhook URL.
For more information about registering a GitHub App, see "注册 GitHub 应用." For more information about changing the webhooks that a GitHub App registration subscribes to, see "修改 GitHub 应用注册."
Choosing a webhook URL
When you activate webhooks for your GitHub App registration, you will need to specify a webhook URL. The webhook URL is the address of a web server that will receive the webhook event payloads sent to your GitHub App. The server can then take action based on the content of the payload. You should choose a web server that's appropriate for the volume of webhook traffic that your GitHub App will encounter.
Choosing a webhook URL for development and testing
While you develop and test your app, you can use a webhook payload delivery service like Smee to capture and forward webhook payloads to your local development environment. Never use Smee for an application in production, because Smee channels are not authenticated or secure. Alternatively, you can use a tool like ngrok, localtunnel, or the Hookdeck Console that exposes your local machine to the internet to receive the payloads.
Creating a webhook URL with Smee
You can use Smee to create a unique domain where GitHub can send webhook payloads, without exposing your local development to the internet. Smee calls this unique domain a "Webhook Proxy URL." You can use Smee's Webhook Proxy URL as the webhook URL for your GitHub App.
- To use Smee to create a unique domain, go to https://smee.io and click Start a new channel.
- On the Smee channel page, follow the instructions under "Use the CLI" to install and run the Smee client.
- To connect your Smee webhook URL to your GitHub App, enter your unique Smee domain in the "Webhook URL" field on your GitHub App registration page. For more information, see "注册 GitHub 应用" and "修改 GitHub 应用注册."
Choosing a webhook URL for production
For an application in production that receives a low volume of webhook traffic, you can host it on any dynamic application server. The server-side code for handling the webhook can receive the event, deserialize its JSON payload, and decide what action to take, such as storing the data in a database or calling the GitHub API.
To handle a higher volume of webhook traffic for a large app in production, consider using asynchronous webhook handling on a dedicated server. You can achieve this by employing a queue, where the webhook handler pushes data to the queue, and separate processes perform subsequent actions based on the events. Additionally, you can use cloud functions such as Azure Functions, AWS Lambda, or Hookdeck to help scale the app for handling large volumes of webhook events.
Securing your webhooks with a webhook secret
Once you've configured your server to receive payloads, it will listen for any payload sent to the server. For security reasons, you should limit incoming requests to only those originating from GitHub. You can do that by creating a webhook secret for your app.
To create a webhook secret for your GitHub App, type a secret token under "Webhook secret" on your GitHub App registration page. You should choose a random string of text with high entropy. For more information, see "注册 GitHub 应用" and "修改 GitHub 应用注册."
After creating a webhook secret for your app, you will need to configure your server to securely store and validate the webhook secret token. For more information, see "保护 Webhook."
Subscribing to webhook events
You can subscribe your GitHub App to receive webhook payloads for specific events. 可以为 GitHub App 注册选择的具体 Webhook 事件根据为应用选择的权限类型而定。 首先需要选择希望应用拥有的权限，然后可以让应用订阅与该权限集相关的 Webhook 事件。 For more information, see "为 GitHub Apps 选择权限."
For example, if you would like your app to receive a webhook event payload whenever a new issue is opened in your repository, you would first need to give your app permission to access "Issues" under "Repository permissions." Then under "Subscribe to events" you can select "Issues."
For more information about the permissions that are required for each webhook event, see "Webhook 事件和有效负载."