docs/content/rest/webhooks/index.md

title, intro, allowTitleToDifferFromFilename, versions, topics, children, redirect_from, autogenerated

title	intro	allowTitleToDifferFromFilename	versions	topics	children	redirect_from	autogenerated
Repository webhooks	Use the REST API to create and manage webhooks for your repositories.	true	fpt ghes ghae ghec * * * *	API	/repo-config /repo-deliveries /repos	/rest/reference/webhooks	rest

About repository webhooks

Repository webhooks allow you to receive HTTP POST payloads whenever certain events happen in a repository. {% data reusables.webhooks.webhooks-rest-api-links %}

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, {% data variables.product.prodname_dotcom %} can also serve as a PubSubHubbub hub for repositories.

Receiving Webhooks

In order for {% data variables.product.product_name %} 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

{% data variables.product.product_name %} 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 "AUTOTITLE."

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 {% data variables.product.api_url_code %}/hub, which takes the following parameters.

Name	Type	Required	Description
hub.mode	string	{% octicon "check" aria-label="Required" %}	Either subscribe or unsubscribe.
hub.topic	string	{% octicon "check" aria-label="Required" %}	The URI of the GitHub repository to subscribe to. The path must be in the format of /{owner}/{repo}/events/{event}.
hub.callback	string	{% octicon "x" aria-label="Optional" %}	The URI to receive the updates to the topic.
hub.secret	string	{% octicon "x" aria-label="Optional" %}	A 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 {% ifversion fpt or ghes or ghec %}X-Hub-Signature or X-Hub-Signature-256 headers{% elsif ghae %}X-Hub-Signature-256 header{% endif %}. You can see the PubSubHubbub documentation for more details.

An example request with curl looks like:

curl --header "Authorization: Bearer YOUR-TOKEN" -i \
  {% data variables.product.api_url_pre %}/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.