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.

The sender property

Most webhook payloads include a sender property identifying the user who triggered the event. Sometimes GitHub can't resolve a specific user, for example when an event comes from an internal process rather than a person, or when the triggering action has no associated user. For some events, such as check_run and check_suite, this includes actions with no Git push or authenticated API actor.

In these cases, sender is populated with the ghost user, a placeholder account whose login is ghost and whose id isn't tied to a real, current user. Don't assume sender always identifies the person who caused an event, and account for the ghost user in any security or business logic that relies on it.

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 event.
• 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/1.1

> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958
> 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": "https://api.github.com/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,
>     ...
>   }
> }