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.
Du kannst die REST-API verwenden, um Repository, Organisation und App-Webhooks zu verwalten. Du kannst Webhookübermittlungen für einen Webhook auflisten oder eine individuelle Übermittlung für einen Webhook abrufen und erneut ausführen, der in eine externe App oder einen Dienst integriert werden kann. Du kannst die REST-API auch verwenden, um die Konfiguration des Webhooks zu ändern. Du kannst beispielsweise die Nutzlast-URL, den Inhaltstyp, die SSL-Überprüfung und das Geheimnis ändern. Weitere Informationen findest du unter:
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.
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."
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.
Nur Mitglieder mit Inhaberberechtigungen für eine Organisation oder Administratorberechtigungen für ein Repository können manage webhooks for an organization. Weitere Informationen findest du unter Rollen in einer Organisation.
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
Hinweis: GitHub-Webhooks unterstützen derzeit nicht IPv6, dies wird aber in Zukunft ergänzt. Der /meta-REST-API-Endpunkt gibt IPv6-Bereiche zurück, um diesen Übergang zu ermöglichen.
Die Payload-URL ist die URL des Servers, der die Webhook-POST-Anforderungen empfängt.
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 können mithilfe unterschiedlicher Inhaltstypen übermittelt werden:
- Der Inhaltstyp
application/jsonbietet die JSON-Nutzdaten direkt als Text derPOST-Anforderung. - Der Inhaltstyp
application/x-www-form-urlencodedsendet die JSON-Nutzdaten als Formularparameter namenspayload.
Wähle die Einstellung aus, die deinen Anforderungen entspricht. For this tutorial, the default content type of application/json is fine.
Secret
Durch das Festlegen eines Webhookgeheimnisses kannst du sicherstellen, dass an die Nutzlast-URL gesendete POST-Anforderungen von GitHub kommen. Wenn du einen geheimen Schlüssel festlegst, erhältst du die Header X-Hub-Signature und X-Hub-Signature-256 in der Webhook-POST-Anforderung. Weitere Informationen dazu, wie du ein Geheimnis mit einem Signaturheader verwendest, um deine Webhooknutzdaten zu schützen, findest du unter Securing your webhooks.
SSL verification
Wenn deine „Nutzlast-URL“ eine sichere Website (HTTPS) ist, hast du die Möglichkeit, die SSL-Überprüfungseinstellungen zu konfigurieren. Wenn deine „Nutzlast-URL“ nicht sicher ist (HTTP), zeigt GitHub diese Option nicht an. Standardmäßig überprüft GitHub das SSL-Zertifikat deiner Website beim Bereitstellen von Webhook-Nutzlasten. Die SSL-Überprüfung stellt sicher, dass Hook-Nutzlasten sicher an deinen URL-Endpunkt übermittelt werden. Du hast die Möglichkeit, SSL zu deaktivieren, aber wir empfehlen, SSL-Überprüfung aktivieren beizubehalten.
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
Wenn du einen neuen Webhook erstellst, senden wir dir ein einfaches ping-Ereignis, um dir mitzuteilen, dass du den Webhook richtig eingerichtet hast. Dieses Ereignis wird nicht gespeichert und ist daher nicht über den Ereignis-API-Endpunkt abrufbar.
For more information about the ping event webhook payload, see the ping event.