Webhook events and payloads

About webhook events and payloads

You can create webhooks that subscribe to the events listed on this page. To limit the number of HTTP requests to your server, you should only subscribe to the specific events that you plan on handling. For more information, see "Creating webhooks."

Each webhook event on this page includes a description of the webhook properties for that event. If the event has multiple actions, the properties corresponding to each action are included.

Each event is only available to specific types of webhooks. For example, an organization webhook can subscribe to the team event, but a repository webhook cannot. The description of each webhook event lists the availability for that event. For more information, see "Types of webhooks."

Payload cap

Payloads are capped at 25 MB. If an event generates a larger payload, GitHub will not deliver a payload for that webhook event. This may happen, for example, on a create event if many branches or tags are pushed at once. We suggest monitoring your payload size to ensure delivery.

Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

• X-GitHub-Hook-ID: The unique identifier of the webhook.
• X-GitHub-Event: The name of the event that triggered the delivery.
• X-GitHub-Delivery: A globally unique identifier (GUID) to identify the delivery.
• X-GitHub-Enterprise-Version: The version of the GitHub Enterprise Server instance that sent the HTTP POST payload.
• X-GitHub-Enterprise-Host: The hostname of the GitHub Enterprise Server instance that sent the HTTP POST payload.
• X-Hub-Signature: This header is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-1 hash function and the secret as the HMAC key. X-Hub-Signature is provided for compatibility with existing integrations. We recommend that you use the more secure X-Hub-Signature-256 instead.
• X-Hub-Signature-256: This header is sent if the webhook is configured with a secret. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key. For more information, see "Validating webhook deliveries."
• User-Agent: This header will always have the prefix GitHub-Hookshot/.
• X-GitHub-Hook-Installation-Target-Type: The type of resource where the webhook was created.
• X-GitHub-Hook-Installation-Target-ID: The unique identifier of the resource where the webhook was created.

To see what each header might look like in a webhook payload, see "Example webhook delivery."

Example webhook delivery

You can choose to have payloads delivered in JSON format (application/json) or as URL-encoded data (x-www-form-urlencoded). Following is an example of a webhook POST request that uses the JSON format.

> POST /payload HTTP/2

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> X-GitHub-Enterprise-Version: 2.15.0
> X-GitHub-Enterprise-Host: example.com
> X-Hub-Signature: sha1=7d38cdd689735b008b3c702edd92eea23791c5f6
> X-Hub-Signature-256: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> User-Agent: GitHub-Hookshot/044aadd
> Content-Type: application/json
> Content-Length: 6615
> X-GitHub-Event: issues
> X-GitHub-Hook-ID: 292430182
> X-GitHub-Hook-Installation-Target-ID: 79929171
> X-GitHub-Hook-Installation-Target-Type: repository

> {
>   "action": "opened",
>   "issue": {
>     "url": "http(s)://<em>HOSTNAME</em>/api/v3/repos/octocat/Hello-World/issues/1347",
>     "number": 1347,
>     ...
>   },
>   "repository" : {
>     "id": 1296269,
>     "full_name": "octocat/Hello-World",
>     "owner": {
>       "login": "octocat",
>       "id": 1,
>       ...
>     },
>     ...
>   },
>   "sender": {
>     "login": "octocat",
>     "id": 1,
>     ...
>   }
> }