github · selvaganesh0355 · Apr 25, 2025
diff --git a/content/webhooks/webhook-events-and-payloads.md b/content/webhooks/webhook-events-and-payloads.md
@@ -1,6 +1,6 @@
 ---
-title: Webhook events and payloads
-intro: Learn about when each webhook event occurs and what the payload contains.
+title: Webhook Events and Payloads
+intro: Understand the various webhook events you can subscribe to and the structure of their payloads.
 redirect_from:
   - /early-access/integrations/webhooks
   - /v3/activity/events/types
@@ -19,42 +19,51 @@ shortTitle: Webhook events & payloads
 autogenerated: webhooks
 ---
 
-## About webhook events and payloads
+## Understanding 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](/webhooks/creating-webhooks).
+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)."
 
-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.
+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.
 
-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).
+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)."
 
-### Payload cap
+### Payload Size Considerations
 
 {% data reusables.webhooks.payload_cap %}
 
-### Delivery headers
+### Examining Delivery Headers
 
-HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:
+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:
 
-* `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](/webhooks/using-webhooks/securing-your-webhooks).
-* `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.
+* `X-GitHub-Hook-ID`: This is a unique identifier assigned to your specific webhook. You can use this to track and manage your webhooks.
+* `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`.
+* `X-GitHub-Delivery`: A universally unique identifier (GUID) for each specific event delivery. This is helpful for debugging and tracking individual webhook calls.
+* `User-Agent`: This header always starts with `GitHub-Hookshot/`, indicating that the request originates from {% data variables.product.prodname_dotcom %}’s webhook system.
+* `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`.
+* `X-GitHub-Hook-Installation-Target-ID`: This is the unique numerical 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).
+{% ifversion ghes %}
 
-### Example webhook delivery
+* `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.
+* `X-GitHub-Enterprise-Host`: For {% data variables.product.prodname_ghe_server %} users, this header contains the hostname of your instance.
 
-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.
+{% endif %}
+
+#### Securing Your Webhooks with Signatures
+
+{% data reusables.webhooks.security-headers %}
+
+* `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`.
+* `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)."
+
+To get a clearer picture of these headers in action, take a look at the "[Example webhook delivery](#example-webhook-delivery)" section below.
+
+### Example Webhook Delivery
+
+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.
 
 ```shell
 > 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 %}
@@ -67,30 +76,35 @@ You can choose to have payloads delivered in JSON format (`application/json`) or
 > 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,
->     ...
->   }
+>    "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,
+>      ...
+>    }
 > }
 ```
+### Quick Webhook Testing
+
+To easily inspect webhook payloads from {% data variables.product.prodname_dotcom %} without a dedicated application, consider these tools:
 
+* **Beeceptor:** Create instant HTTP endpoints to inspect headers and payloads. Visit [https://beeceptor.com/](https://beeceptor.com/).
+* **HTTPBin:** Use the `/post` endpoint to see the details of your webhook requests at [https://httpbin.org/](https://httpbin.org/).
 <!-- Content after this section is automatically generated -->