webhooks: document the undocumented pieces of the push webhook (#21792)

Co-authored-by: Sarah Edwards <skedwards88@github.com>

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

@@ -1032,10 +1032,15 @@ Deliveries for `review_requested` and `review_request_removed` events will have
 
 Key | Type | Description
 ----|------|-------------
-`ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main`.
+`ref`|`string` | The full [`git ref`](/rest/reference/git#refs) that was pushed. Example: `refs/heads/main` or `refs/tags/v3.14.1`.
 `before`|`string` | The SHA of the most recent commit on `ref` before the push.
 `after`|`string` | The SHA of the most recent commit on `ref` after the push.
-`commits`|`array` | An array of commit objects describing the pushed commits. (The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.)
+`created`|`boolean` | Whether this push created the `ref`.
+`deleted`|`boolean` | Whether this push deleted the `ref`.
+`forced`|`boolean` | Whether this push was a force push of the `ref`.
+`head_commit`|`object` | For pushes where `after` is or points to a commit object, an expanded representation of that commit. For pushes where `after` refers to an annotated tag object,  an expanded representation of the commit pointed to by the annotated tag.
+`compare`|`string` | URL that shows the changes in this `ref` update, from the `before` commit to the `after` commit. For a newly created `ref` that is directly based on the default branch, this is the comparison between the head of the default branch and the `after` commit. Otherwise, this shows all commits until the `after` commit.
+`commits`|`array` | An array of commit objects describing the pushed commits. (Pushed commits are all commits that are included in the `compare` between the `before` commit and the `after` commit.) The array includes a maximum of 20 commits. If necessary, you can use the [Commits API](/rest/reference/repos#commits) to fetch additional commits. This limit is applied to timeline events only and isn't applied to webhook deliveries.
 `commits[][id]`|`string` | The SHA of the commit.
 `commits[][timestamp]`|`string` | The ISO 8601 timestamp of the commit.
 `commits[][message]`|`string` | The commit message.

lib/webhooks/static/dotcom/push.payload.json

@@ -1,16 +1,38 @@
 {
   "ref": "refs/tags/simple-tag",
-  "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
-  "after": "0000000000000000000000000000000000000000",
-  "created": false,
-  "deleted": true,
+  "before": "0000000000000000000000000000000000000000",
+  "after": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+  "created": true,
+  "deleted": false,
   "forced": false,
-  "base_ref": null,
-  "compare": "https://github.com/Codertocat/Hello-World/compare/6113728f27ae...000000000000",
+  "base_ref": "refs/heads/main",
+  "compare": "https://github.com/Codertocat/Hello-World/compare/simple-tag",
   "commits": [
 
   ],
-  "head_commit": null,
+  "head_commit": {
+    "id": "6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+    "tree_id": "4b825dc642cb6eb9a060e54bf8d69288fbee4904",
+    "distinct": true,
+    "message": "Adding a .gitignore file",
+    "timestamp": "2019-05-15T15:20:41Z",
+    "url": "https://github.com/Codertocat/Hello-World/commit/6113728f27ae82c7b1a177c8d03f9e96e0adf246",
+    "author": {
+      "name": "Codertocat",
+      "email": "21031067+Codertocat@users.noreply.github.com",
+      "username": "Codertocat"
+    },
+    "committer": {
+      "name": "Codertocat",
+      "email": "21031067+Codertocat@users.noreply.github.com",
+      "username": "Codertocat"
+    },
+    "added": [
+      ".gitignore"
+    ],
+    "removed": [ ],
+    "modified": [ ]
+  },
   "repository": {
     "id": 186853002,
     "node_id": "MDEwOlJlcG9zaXRvcnkxODY4NTMwMDI=",