Skip to content

Commit 7164ae9

Browse files
selvaganesh0355selvaganesh0355
authored
Update webhook-events-and-payloads.md
1 parent d4a47ab commit 7164ae9

File tree

1 file changed

+59
-45
lines changed

1 file changed

+59
-45
lines changed

‎content/webhooks/webhook-events-and-payloads.md‎

Lines changed: 59 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Webhook events and payloads
3-
intro: Learn about when each webhook event occurs and what the payload contains.
2+
title: Webhook Events and Payloads
3+
intro: Understand the various webhook events you can subscribe to and the structure of their payloads.
44
redirect_from:
55
- /early-access/integrations/webhooks
66
- /v3/activity/events/types
@@ -19,42 +19,51 @@ shortTitle: Webhook events & payloads
1919
autogenerated: webhooks
2020
---
2121

22-
## About webhook events and payloads
22+
## Understanding Webhook Events and Payloads
2323

24-
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](/webhooks/creating-webhooks).
24+
Webhooks enable you to build or set up integrations that subscribe to specific events on {% data variables.product.prodname_dotcom %}. When one of those events is triggered, {% data variables.product.prodname_dotcom %} sends an HTTP POST request to the webhook's configured URL. To minimize the load on your server, it's crucial to subscribe only to the events your integration needs to handle. You can learn more about setting up webhooks in "[Creating Webhooks](/webhooks/creating-webhooks)."
2525

26-
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.
26+
On this page, you'll find a detailed description of the properties included in the webhook payload for each event. If an event has multiple associated actions (for example, an issue can be `opened`, `closed`, or `edited`), you'll see the specific properties relevant to each action.
2727

28-
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](/webhooks/types-of-webhooks).
28+
Keep in mind that the availability of certain webhook events depends on the type of webhook you're creating. For instance, an organization webhook can subscribe to `team` events, while a repository webhook cannot. The description for each event clearly indicates its availability. For more details, refer to "[Types of Webhooks](/webhooks/types-of-webhooks)."
2929

30-
### Payload cap
30+
### Payload Size Considerations
3131

3232
{% data reusables.webhooks.payload_cap %}
3333

34-
### Delivery headers
34+
### Examining Delivery Headers
3535

36-
HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:
36+
When {% data variables.product.prodname_dotcom %} sends an HTTP POST request to your webhook's URL, it includes several custom headers that provide valuable context about the delivery:
3737

38-
* `X-GitHub-Hook-ID`: The unique identifier of the webhook.
39-
* `X-GitHub-Event`: The name of the event that triggered the delivery.
40-
* `X-GitHub-Delivery`: A globally unique identifier (GUID) to identify the event.{% ifversion ghes %}
41-
* `X-GitHub-Enterprise-Version`: The version of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.
42-
* `X-GitHub-Enterprise-Host`: The hostname of the {% data variables.product.prodname_ghe_server %} instance that sent the HTTP POST payload.{% endif %}
43-
* `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.
44-
* `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](/webhooks/using-webhooks/securing-your-webhooks).
45-
* `User-Agent`: This header will always have the prefix `GitHub-Hookshot/`.
46-
* `X-GitHub-Hook-Installation-Target-Type`: The type of resource where the webhook was created.
47-
* `X-GitHub-Hook-Installation-Target-ID`: The unique identifier of the resource where the webhook was created.
38+
* `X-GitHub-Hook-ID`: This is a unique identifier assigned to your specific webhook. You can use this to track and manage your webhooks.
39+
* `X-GitHub-Event`: This header specifies the exact name of the event that triggered the webhook delivery. For example, it might be `issues`, `pull_request`, or `push`.
40+
* `X-GitHub-Delivery`: A universally unique identifier (GUID) for each specific event delivery. This is helpful for debugging and tracking individual webhook calls.
41+
* `User-Agent`: This header always starts with `GitHub-Hookshot/`, indicating that the request originates from {% data variables.product.prodname_dotcom %}’s webhook system.
42+
* `X-GitHub-Hook-Installation-Target-Type`: This indicates the type of resource where the webhook was created. Possible values include `repository`, `organization`, or `marketplace_account`.
43+
* `X-GitHub-Hook-Installation-Target-ID`: This is the unique numerical identifier of the resource where the webhook was created.
4844

49-
To see what each header might look like in a webhook payload, see [Example webhook delivery](#example-webhook-delivery).
45+
{% ifversion ghes %}
5046

51-
### Example webhook delivery
47+
* `X-GitHub-Enterprise-Version`: If you're using {% data variables.product.prodname_ghe_server %}, this header provides the specific version of your instance that sent the webhook payload.
48+
* `X-GitHub-Enterprise-Host`: For {% data variables.product.prodname_ghe_server %} users, this header contains the hostname of your instance.
5249

53-
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.
50+
{% endif %}
51+
52+
#### Securing Your Webhooks with Signatures
53+
54+
{% data reusables.webhooks.security-headers %}
55+
56+
* `X-Hub-Signature`: This header is present if you've configured a `secret` for your webhook. It contains the HMAC-SHA1 hash of the request body, using your `secret` as the key. While provided for backward compatibility, we recommend using the more secure `X-Hub-Signature-256`.
57+
* `X-Hub-Signature-256`: This header is also sent when a `secret` is configured. It contains the HMAC-SHA256 hash of the request body, offering a stronger level of security. For detailed information on securing your webhooks, see "[Securing your webhooks](/webhooks/using-webhooks/securing-your-webhooks)."
58+
59+
To get a clearer picture of these headers in action, take a look at the "[Example webhook delivery](#example-webhook-delivery)" section below.
60+
61+
### Example Webhook Delivery
62+
63+
You have the flexibility to choose whether webhook payloads are delivered in JSON format (`application/json`) or as URL-encoded data (`x-www-form-urlencoded`). The following example illustrates a webhook POST request using the more common JSON format.
5464

5565
```shell
5666
> POST /payload HTTP/1.1
57-
5867
> X-GitHub-Delivery: 72d3162e-cc78-11e3-81ab-4c9367dc0958{% ifversion ghes %}
5968
> X-GitHub-Enterprise-Version: 2.15.0
6069
> X-GitHub-Enterprise-Host: example.com{% endif %}
@@ -67,30 +76,35 @@ You can choose to have payloads delivered in JSON format (`application/json`) or
6776
> X-GitHub-Hook-ID: 292430182
6877
> X-GitHub-Hook-Installation-Target-ID: 79929171
6978
> X-GitHub-Hook-Installation-Target-Type: repository
70-
79+
>
7180
> {
72-
> "action": "opened",
73-
> "issue": {
74-
> "url": "{% data variables.product.rest_url %}/repos/octocat/Hello-World/issues/1347",
75-
> "number": 1347,
76-
> ...
77-
> },
78-
> "repository" : {
79-
> "id": 1296269,
80-
> "full_name": "octocat/Hello-World",
81-
> "owner": {
82-
> "login": "octocat",
83-
> "id": 1,
84-
> ...
85-
> },
86-
> ...
87-
> },
88-
> "sender": {
89-
> "login": "octocat",
90-
> "id": 1,
91-
> ...
92-
> }
81+
> "action": "opened",
82+
> "issue": {
83+
> "url": "{% data variables.product.rest_url %}/repos/octocat/Hello-World/issues/1347",
84+
> "number": 1347,
85+
> ...
86+
> },
87+
> "repository" : {
88+
> "id": 1296269,
89+
> "full_name": "octocat/Hello-World",
90+
> "owner": {
91+
> "login": "octocat",
92+
> "id": 1,
93+
> ...
94+
> },
95+
> ...
96+
> },
97+
> "sender": {
98+
> "login": "octocat",
99+
> "id": 1,
100+
> ...
101+
> }
93102
> }
94103
```
104+
### Quick Webhook Testing
105+
106+
To easily inspect webhook payloads from {% data variables.product.prodname_dotcom %} without a dedicated application, consider these tools:
95107
108+
* **Beeceptor:** Create instant HTTP endpoints to inspect headers and payloads. Visit [https://beeceptor.com/](https://beeceptor.com/).
109+
* **HTTPBin:** Use the `/post` endpoint to see the details of your webhook requests at [https://httpbin.org/](https://httpbin.org/).
96110
<!-- Content after this section is automatically generated -->

0 commit comments

Comments
 (0)