Skip to content

webhook-events-and-payloads.md

Latest commit

 

History

History
102 lines (83 loc) · 5.31 KB

webhook-events-and-payloads.md

File metadata and controls

102 lines (83 loc) · 5.31 KB
Raw
title Webhook events and payloads
intro Learn about when each webhook event occurs and what the payload contains.
redirect_from
/early-access/integrations/webhooks
/v3/activity/events/types
/webhooks/event-payloads
/developers/webhooks-and-events/webhook-events-and-payloads
/developers/webhooks-and-events/webhooks/webhook-events-and-payloads
/webhooks-and-events/webhooks/webhook-events-and-payloads
/webhooks/webhooks/webhook-events-and-payloads
versions
fpt ghes ghec
*
*
*
shortTitle Webhook events & payloads
autogenerated webhooks
category
Handle webhook deliveries

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 AUTOTITLE.

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 AUTOTITLE.

The sender property

Most webhook payloads include a sender property identifying the user who triggered the event. Sometimes {% data variables.product.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

{% data reusables.webhooks.payload_cap %}

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.{% ifversion ghes %}
  • X-GitHub-Enterprise-Version: The version of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.
  • X-GitHub-Enterprise-Host: The hostname of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.{% endif %}
  • 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 AUTOTITLE.
  • 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{% ifversion ghes %}
> X-GitHub-Enterprise-Version: 2.15.0
> X-GitHub-Enterprise-Host: example.com{% endif %}
> 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": "{% data variables.product.rest_url %}/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,
>     ...
>   }
> }