a340162d84
Co-authored-by: Lucas Costi <lucascosti@users.noreply.github.com> Co-authored-by: Peter Bengtsson <peterbe@github.com>
96 lines
4.4 KiB
Markdown
96 lines
4.4 KiB
Markdown
---
|
|
title: Webhooks
|
|
intro: 'The webhooks API allows you to create and manage webhooks for your repositories.'
|
|
allowTitleToDifferFromFilename: true
|
|
versions:
|
|
fpt: '*'
|
|
ghes: '*'
|
|
ghae: '*'
|
|
ghec: '*'
|
|
topics:
|
|
- API
|
|
miniTocMaxHeadingLevel: 3
|
|
---
|
|
|
|
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](/rest/reference/orgs#webhooks).
|
|
|
|
In addition to the REST API, {% data variables.product.prodname_dotcom %} can also serve as a [PubSubHubbub](#pubsubhubbub) hub for repositories.
|
|
|
|
{% for operation in currentRestOperations %}
|
|
{% unless operation.subcategory %}{% include rest_operation %}{% endunless %}
|
|
{% endfor %}
|
|
|
|
## Repository webhooks
|
|
|
|
{% for operation in currentRestOperations %}
|
|
{% if operation.subcategory == 'repos' %}{% include rest_operation %}{% endif %}
|
|
{% endfor %}
|
|
|
|
## Repository webhook configuration
|
|
|
|
{% for operation in currentRestOperations %}
|
|
{% if operation.subcategory == 'repo-config' %}{% include rest_operation %}{% endif %}
|
|
{% endfor %}
|
|
|
|
## Repository webhook deliveries
|
|
|
|
{% for operation in currentRestOperations %}
|
|
{% if operation.subcategory == 'repo-deliveries' %}{% include rest_operation %}{% endif %}
|
|
{% endfor %}
|
|
|
|
## 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](/developers/webhooks-and-events/webhook-events-and-payloads#delivery-headers) for details.
|
|
|
|
## PubSubHubbub
|
|
|
|
GitHub can also serve as a [PubSubHubbub](https://github.com/pubsubhubbub/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](/developers/webhooks-and-events/webhook-events-and-payloads)."
|
|
|
|
### Response format
|
|
|
|
The default format is what [existing post-receive hooks should expect](/post-receive-hooks/): 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:
|
|
|
|
``` shell
|
|
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 > 2.22 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](https://pubsubhubbub.github.io/PubSubHubbub/pubsubhubbub-core-0.4.html#authednotify) for more details.
|