Skip to main content

This version of GitHub Enterprise was discontinued on 2023-07-06. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

After a site administrator upgrades your Enterprise Server instance to Enterprise Server 3.9 or later, the REST API will be versioned. To learn how to find your instance's version, see "About versions of GitHub Docs". For more information, see "About API versioning."

Repository webhooks

Use the REST API to create and manage webhooks for your repositories.

About repository webhooks

Repository webhooks allow you to receive HTTP POST payloads whenever certain events happen in a repository. You can use the REST API to manage repository, organization, and app webhooks. You can list webhook deliveries for a webhook, or get and redeliver an individual delivery for a webhook, which can be integrated into an external app or service. You can also use the REST API to change the configuration of the webhook. For example, you can modify the payload URL, content type, SSL verification, and secret. For more information, see:

If you would like to set up a single webhook to receive events from all of your organization's repositories, see our REST API documentation for Organization Webhooks.

In addition to the REST API, GitHub can also serve as a PubSubHubbub hub for repositories.

Receiving Webhooks

In order for GitHub Enterprise Server to send webhook payloads, your server needs to be accessible from the Internet. We also highly suggest using SSL so that we can send encrypted payloads over HTTPS.

Webhook headers

GitHub Enterprise Server will send along several HTTP headers to differentiate between event types and payload identifiers. See webhook headers for details.

PubSubHubbub

GitHub can also serve as a PubSubHubbub hub for all repositories. PSHB is a simple publish/subscribe protocol that lets servers register to receive updates when a topic is updated. The updates are sent with an HTTP POST request to a callback URL. Topic URLs for a GitHub repository's pushes are in this format:

https://github.com/{owner}/{repo}/events/{event}

The event can be any available webhook event. For more information, see "Webhook events and payloads."

Response format

The default format is what existing post-receive hooks should expect: A JSON body sent as the payload parameter in a POST. You can also specify to receive the raw JSON body with either an Accept header, or a .json extension.

Accept: application/json
https://github.com/{owner}/{repo}/events/push.json

Callback URLs

Callback URLs can use the HTTP protocol.

# Send updates to a PostBin bin
https://www.toptal.com/developers/postbin/123

Subscribing

The GitHub PubSubHubbub endpoint is http(s)://HOSTNAME/api/v3/hub, which takes the following parameters.

NameTypeRequiredDescription
hub.modestringEither subscribe or unsubscribe.
hub.topicstringThe URI of the GitHub repository to subscribe to. The path must be in the format of /{owner}/{repo}/events/{event}.
hub.callbackstringThe URI to receive the updates to the topic.
hub.secretstringA shared secret key that generates a hash signature of the outgoing body content. You can verify a push came from GitHub by comparing the raw request body with the contents of the X-Hub-Signature or X-Hub-Signature-256 headers. You can see the PubSubHubbub documentation for more details.

An example request with curl looks like:

curl --header "Authorization: Bearer YOUR-TOKEN" -i \
  http(s)://HOSTNAME/api/v3/hub \
  -F "hub.mode=subscribe" \
  -F "hub.topic=https://github.com/{owner}/{repo}/events/push" \
  -F "hub.callback=https://www.toptal.com/developers/postbin/123"

PubSubHubbub requests can be sent multiple times. If the hook already exists, it will be modified according to the request.