docs/content/rest/webhooks/index.md

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

title	intro	allowTitleToDifferFromFilename	versions	topics	miniTocMaxHeadingLevel	children	redirect_from
Webhooks	The webhooks API allows you to create and manage webhooks for your repositories.	true	fpt ghes ghae ghec * * * *	API	3	/repo-config /repo-deliveries /repos	/rest/reference/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 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 "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 postbin.org
http://postbin.org/123

Subscribing

The GitHub PubSubHubbub endpoint is: {% data variables.product.api_url_code %}/hub. A successful request with curl looks like:

curl -u "user" -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=http://postbin.org/123"

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

Parameters

Name	Type	Description
hub.mode	string	Required. Either subscribe or unsubscribe.
hub.topic	string	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	The URI to receive the updates to the topic.
hub.secret	string	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 > 3.0 or ghec %}X-Hub-Signature or X-Hub-Signature-256 headers{% elsif ghes < 3.0 %}X-Hub-Signature header{% elsif ghae %}X-Hub-Signature-256 header{% endif %}. You can see the PubSubHubbub documentation for more details.