updating merge api and adding webhooks to programmatic reference (#62621)

dihydroJenoxide · vgrl · web-flow · commit 7b813bc6345e · 2026-08-05T17:30:03.000Z
Co-authored-by: Vanessa &lt;vgrl@github.com&gt;
diff --git a/content/pull-requests/get-started/about-stacked-prs.md b/content/pull-requests/get-started/about-stacked-prs.md
@@ -113,7 +113,7 @@ You can merge your entire stack, a single pull request, or a portion of the stac
 Stacks support merge commit, squash, and rebase merge methods, and they are merge-queue aware. The resulting commit history is the same as merging each pull request individually, starting from the bottom.
 
 > [!NOTE]
-> If you merge via the API and want to use stacked pull requests, you'll need to update to use the new merge API for stacks. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
+> If you merge via the API and want to use stacked pull requests, you'll need to use the asynchronous merge API for stacks. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
 
 ## Next steps
 
diff --git a/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests.md b/content/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests.md
@@ -27,7 +27,7 @@ The merge box for a stacked pull request shows the status of the entire stack, n
 If the stack is not linear, for example, after changes were pushed to a lower branch or after the trunk moved ahead, a **Rebase stack** button will appear in the merge box and you'll need to rebase the stack before you can merge.
 
 > [!NOTE]
-> * If you merge via the API and want to use stacked pull requests, you'll need to update your code to use the new merge API for stacks. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
+> * If you merge via the API and want to use stacked pull requests, you'll need use the asynchronous merge API for stacks. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
 > * Auto-merge is not supported for stacked pull requests.
 
 ## Merging using a merge queue
diff --git a/content/pull-requests/how-tos/stacked-pull-requests/index.md b/content/pull-requests/how-tos/stacked-pull-requests/index.md
@@ -23,7 +23,7 @@ children:
   - /content/pull-requests/tutorials/stack-code-changes-in-pull-requests
   - /content/pull-requests/reference/stacked-pull-requests
   - /content/pull-requests/reference/stacked-prs-cli-commands
-  - /content/pull-requests/reference/stacked-pull-requests-rest-and-graphql-apis
+  - /content/pull-requests/reference/stacked-pull-requests-apis-and-webhooks
   - /content/rest/pulls/pulls
   - /content/graphql/reference/pulls
   - /content/webhooks/webhook-events-and-payloads
diff --git a/content/pull-requests/index.md b/content/pull-requests/index.md
@@ -9,20 +9,19 @@ redirect_from:
   - /categories/collaborating-on-projects-using-issues-and-pull-requests
   - /categories/collaborating-with-issues-and-pull-requests
   - /github/collaborating-with-pull-requests
-intro: 'Discover how to create, review, and merge pull requests, resolve merge conflicts, and collaborate effectively on {% data variables.product.github %} projects.'
+intro: 'Discover how to create, review, and merge pull requests, resolve merge conflicts, and work with forks.'
 introLinks:
   overview: /pull-requests/get-started/about-pull-requests
 layout: discovery-landing
 carousels:
   recommended:
-    - /pull-requests/reference/pull-requests
+    - /pull-requests/get-started/about-pull-requests
     - /pull-requests/reference/branches
     - /pull-requests/how-tos/create-pull-requests/creating-a-pull-request
     - /pull-requests/how-tos/review-pull-requests/reviewing-proposed-changes-in-a-pull-request
     - /pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request
     - /pull-requests/how-tos/merge-and-close-pull-requests/resolving-a-merge-conflict-on-github
     - /pull-requests/how-tos/work-with-forks/fork-a-repo
-    - /pull-requests/how-tos/work-with-forks/syncing-a-fork
     - /pull-requests/reference/commits
 includedCategories:
   - Create pull requests
diff --git a/content/pull-requests/reference/index.md b/content/pull-requests/reference/index.md
@@ -10,7 +10,7 @@ children:
   - /pull-requests
   - /stacked-pull-requests
   - /stacked-prs-cli-commands
-  - /stacked-pull-requests-rest-and-graphql-apis
+  - /stacked-pull-requests-apis-and-webhooks
   - /branches
   - /forks
   - /commits
diff --git a/content/pull-requests/reference/stacked-pull-requests-apis-and-webhooks.md b/content/pull-requests/reference/stacked-pull-requests-apis-and-webhooks.md
@@ -1,13 +1,16 @@
 ---
-title: Stacked pull requests in the REST and GraphQL APIs
-shortTitle: Stacked PRs APIs
-intro: Read and manage stacked pull requests programmatically with the {% data variables.product.github %} REST and GraphQL APIs.
+title: Stacked pull requests APIs and webhooks
+shortTitle: Stacked PRs APIs and webhooks
+intro: Read and manage stacked pull requests programmatically with the {% data variables.product.github %} REST and GraphQL APIs, and webhooks.
 allowTitleToDifferFromFilename: true
+redirect_from:
+  - /pull-requests/reference/stacked-pull-requests-rest-and-graphql-apis
 versions:
   feature: pr-stacks
 contentType: reference
 category:
   - Create pull requests
+  - Merge and close pull requests
 ---
 
 {% data reusables.public-preview.public-preview %}
@@ -23,11 +26,21 @@ The REST API exposes stacked pull requests in two ways:
 * **The `stack` object on pull request resources.** When a pull request belongs to a stack, its REST resource includes a `stack` object. This lets you read the pull request's stack membership, including the stack's number and size and the pull request's position and base, directly from the pull request.
 * **The Stacks API.** A dedicated set of endpoints to list, read, create, extend, and dissolve stacks. This is the surface for creating and modifying stacks.
 
-> [!NOTE]
-> If you merge via the API and want to use stacked pull requests, you'll need to update your code to use the new merge API for stacks. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
-
 For endpoints, parameters, and schemas, see [AUTOTITLE](/rest/pulls/pulls).
 
+> [!IMPORTANT]
+> If you merge via the API and want to use stacked pull requests, you must use the new asynchronous merge API.
+
+### Merge API
+
+When you merge a stacked pull request via the API, you must use the asynchronous merge endpoint.
+
+A stack cannot be merged with the legacy synchronous merge endpoints or mutations. When you merge a stacked pull request, every pull request in the stack up to and including the one you request is merged or queued to merge into the base branch. Merging a pull request stack may involve several pull requests that may take a few minutes to merge. Because of this, the merge runs in the background when you submit a merge request and then you can poll for the result.
+
+Only the basic pull request state is checked when you submit an open PR. Branch protection and repository rules are evaluated later, when the merge actually runs, and a rule failure is reported as a failed result while polling. A stack merge request is atomic, meaning either the whole group of pull requests merges, or is added to the merge queue, or none of it is.
+
+For details, see [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
+
 ## GraphQL API
 
 The GraphQL API exposes a pull request's stack membership through read-only `stack` and `stackEntry` fields on the `PullRequest` type. Use these fields to query the stack a pull request belongs to and its position within it.
@@ -36,6 +49,14 @@ The GraphQL API is read-only for stacks; there are no stack mutations. To create
 
 For fields, objects, and schemas, see [AUTOTITLE](/graphql/reference/pulls#object-pullrequeststack).
 
+## Webhooks
+
+When a pull request belongs to a stack, {% data variables.product.github %} adds a `stack` property to the `pull_request` object in webhook event payloads. This lets apps and integrations inspect the stack's target branch, not just the direct parent branch of the pull request.
+
+The `stack` object is included in the `pull_request` webhook payload for pull request lifecycle events that happen while the pull request is part of a stack.
+
+See [AUTOTITLE](/webhooks/webhook-events-and-payloads?actionType=stacked#pull_request).
+
 ## Further reading
 
 * [AUTOTITLE](/pull-requests/reference/stacked-prs-cli-commands)
diff --git a/content/pull-requests/tutorials/roll-out-stacked-prs.md b/content/pull-requests/tutorials/roll-out-stacked-prs.md
@@ -67,11 +67,11 @@ To sustain adoption, review any in-house tools, bots, or dashboards that create,
 If your organization provides an internal CLI or other developer tooling, you can use the Stacks API to integrate stack creation and management into those existing tools instead of requiring developers to adopt `gh stack`.
 
 > [!IMPORTANT]
-> Merging a stacked pull request programmatically requires the asynchronous merge API, which supports both stacked and standalone pull requests. The legacy pull request merge endpoint can't merge a stack. If your organization merges pull requests programmatically, update that tooling to use the asynchronous merge API before rolling out stacked pull requests. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
+> Merging a stacked pull request requires the asynchronous merge API. The legacy pull request merge endpoints can't merge a stack. If your organization merges pull requests programmatically, for example, through in-house tooling or ChatOps bots, update that tooling to call the asynchronous merge API, which supports both stacked and regular pull requests, before rolling out stacked pull requests. See [AUTOTITLE](/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously).
 
 You may also want to track stack activity programmatically, for example, across dashboards, bots, or internal tooling.
 
-* **REST API**: Every pull request returned by the API includes a `stack` object when it belongs to a stack, showing the stack's number, size, the pull request's position within it, and the stack's base branch. A dedicated Stacks API (`GET /repos/{owner}/{repo}/stacks`) also lists every stack in a repository, or the specific stack containing a given pull request. See [AUTOTITLE](/pull-requests/reference/stacked-pull-requests-rest-and-graphql-apis).
+* **REST API**: Every pull request returned by the API includes a `stack` object when it belongs to a stack, showing the stack's number, size, the pull request's position within it, and the stack's base branch. A dedicated Stacks API (`GET /repos/{owner}/{repo}/stacks`) also lists every stack in a repository, or the specific stack containing a given pull request. See [AUTOTITLE](/pull-requests/reference/stacked-pull-requests-apis-and-webhooks).
 * **Webhooks**: The `pull_request` webhook payload includes the same `stack` object whenever a pull request belongs to a stack. A dedicated `stacked` action fires when a pull request is first added to a stack, so you can react the moment a stack forms.
 
 In both cases, the `stack` field is `null` for standalone pull requests, so existing integrations that don't expect stacks continue to work unchanged.
