Splitting webhook integration content over separate pages

jekyll/_cci2/custom-webhooks.adoc

@@ -0,0 +1,126 @@
+---
+contentTags:
+  platform:
+  - Cloud
+  - Server v4+
+---
+= Custom webhooks
+:page-layout: classic-docs
+:page-description: Use webhooks to integrate with third-party services and subscribe to CircleCI events
+:icons: font
+:experimental:
+
+Setting up an inbound webhook (as a **custom webhook** trigger) on CircleCI enables a third party service to trigger a CircleCI pipeline. Any service that can send a webhook or make a `curl` request can trigger a CircleCI pipeline.
+
+=== Introduction
+
+NOTE: Custom webhooks are available for projects integrated via the GitHub App. Custom webhooks are not available on CircleCI server.
+
+Use **custom webhooks** to trigger a pipeline from anywhere that can emit a webhook or run a curl command.
+
+TIP: Custom webhooks are inbound to CircleCI and are used to trigger pipelines from other services. If you are looking for a way to have a CircleCI pipeline trigger a service, use an xref:outbound-webhooks#[outbound webhook].
+
+=== Quickstart
+
+
+Follow these steps to set up and test a custom webhook trigger. Trigger from anywhere that can emit a webhook or run a curl command:
+
+include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
+
+. You can now test your custom webhook trigger with `curl`. To trigger your pipeline, copy and paste the following sample request and replace `<your-URL>` and `<your-secret>` with the URL and secret that you generated in the previous step:
++
+NOTE: When triggering via `curl`, you must use a `POST` request with `content-type: application/json`.
++
+[,shell]
+----
+curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'
+----
+
+See our link:https://discuss.circleci.com/t/trigger-pipelines-from-anywhere-inbound-webhooks-now-in-preview/49864[community forum] for more details or how to use this functionality with a link:https://discuss.circleci.com/t/re-build-automatically-when-new-image-is-available-on-dockerhub/50350[3rd party service like DockerHub].
+
+NOTE: Custom webhooks will not work with xref:contexts#security-group-restrictions[security group restrictions].  Additionally, the configuration file that is used for pipelines triggered by a custom webhook will only be visible in the CircleCI web app if the configuration file path is `.circleci/config.yml`.
+
+
+=== Example: Trigger one pipeline from another
+
+Use a custom webhook to configure one pipeline to trigger a second pipeline. For example, you might need to run a set of integration tests on a repository after you have made a change to a separate repository.
+
+For this example, assume you have two projects in separate repositories:
+
+TIP: You can also use this method to trigger one pipeline from another within the _same_ project.
+
+* Project A
+* Project B
+
+When a change is made to Project A, we want the full Project A configuration to be run, and then the Project B pipeline should be triggered. To achieve this, follow these steps:
+
+==== 1. Set up a custom webhook trigger in Project B
+
+Navigate to Project B in the CircleCI web app and set up a custom webhook by following these steps:
+
+include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
+
+==== 2. Configure Project A to trigger a pipeline in Project B
+
+Navigate to Project A in the CircleCI web app and set up an environment variable. The value of the environment variable will be the secret from the custom webhook you just set up for Project B.
+
+TIP: As an alternative, you can add an environment variable using a xref:contexts#[context].
+
+. In the link:https://app.circleci.com/[CircleCI web app] select your organization.
+. Select **Projects** in the sidebar.
+. Find your project in the list, select the ellipsis (icon:ellipsis-h[]), and select **Project Settings**.
+. Select **Environment Variables** from the sidebar.
+. Select btn:[Add Environment Variable].
+. Give your environment variable a name, for example, `WEBHOOK_SECRET`.
+. Update your Project A configuration file with a step that will trigger a pipeline for Project B, for example (lines 13-16):
++
+[,yaml]
+----
+version: 2.1
+
+jobs:
+  say-hello:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - checkout
+      - run:
+          name: example
+          command: echo "one step"
+
+      - run:
+          name: Kick off new pipeline
+          command: |
+              curl -X POST -H "content-type: application/json" "https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=${WEBHOOK_SECRET}"
+
+workflows:
+  say-hello-workflow:
+    jobs:
+      - say-hello
+----
+
+=== Example: Extract custom webhook payload data
+
+The custom webhook body is available by using the `pipeline.trigger_parameters.webhook.body` xref:variables#pipeline-values[pipeline value].
+
+The following example shows how you can use `jq` to extract values from the webhook payload into environment variables when you want to use them in your configuration.
+
+In this example the webhook body contains a property called `branch`. `jq` is installed and used to extract the `branch` value into an environment variable named `WEBHOOK_BRANCH`, which is then used in a GitHub clone command.
+
+TIP: The xref:configuration-reference#commands[command] configured in this example uses commands from the link:https://circleci.com/developer/orbs/orb/circleci/jq[jq] and link:https://circleci.com/developer/orbs/orb/circleci/github-cli[GitHub CLI] orbs.
+
+[,yaml]
+----
+commands:
+  shallow_clone:
+    description: Shallow Git Clone
+    steps:
+      - gh/setup:
+          token: "GITHUB_TOKEN"
+      - jq/install
+      - run:
+          name: Shallow Clone
+          command: |
+            WEBHOOK_BRANCH=$(echo '<< pipeline.trigger_parameters.webhook.body >>' | jq '.branch')
+            gh repo clone << pipeline.trigger_parameters.github_app.repo_url >> . -- --depth 10 --branch "$WEBHOOK_BRANCH"
+----

jekyll/_cci2/github-apps-integration.adoc

@@ -131,7 +131,7 @@ A subset of built-in environment variables are not available in GitHub-based pro
 
 CircleCI's GitHub App integration provides fine-grained permissions, uses short-lived tokens, and gives you more control over which repositories CircleCI has access to.  The CircleCI GitHub App also enables the following functions:
 
-* xref:webhooks#custom-webhooks[Custom webhooks]
+* xref:custom-webhooks#[Custom webhooks]
 * link:https://discuss.circleci.com/t/circleci-config-suggestions-bot/47918[CircleCI's config suggestions bot]
 * The ability to use xref:set-up-multiple-configuration-files-for-a-project#[multiple configuration files within one project]
 
@@ -195,7 +195,7 @@ You cannot currently manage the connection with GitHub outside of the project se
 [#scheduled-pipelines]
 === Scheduled pipelines
 
-The ability to xref:scheduled-pipelines#[schedule pipelines] is not currently supported for GitHub App projects. This feature is planned for a future release. As an alternative, use a xref:webhooks#custom-webhooks[custom webhook] or the xref:triggers-overview/#run-a-pipeline-using-the-api[V2 API to trigger a pipeline], which you can `curl` with a 3rd party scheduling tool.
+The ability to xref:scheduled-pipelines#[schedule pipelines] is not currently supported for GitHub App projects. This feature is planned for a future release. As an alternative, use a xref:custom-webhooks#[custom webhook] or the xref:triggers-overview/#run-a-pipeline-using-the-api[V2 API to trigger a pipeline], which you can `curl` with a 3rd party scheduling tool.
 
 [#build-forked-pull-requests]
 === Build forked pull requests

jekyll/_cci2/github-integration.adoc

@@ -338,7 +338,7 @@ Key functionality enabled through the GitHub App integration includes the follow
 * The option to have **multiple pipelines in the same project**, each defined in its own YAML file.
 * The possibility to set up your pipelines so that the **config file and the application code are stored in different repositories**. Refer to the link:https://circleci.com/changelog/unlocking-any-cross-repo-pipeline-and-trigger-setups-including-central/[changelog entry] for more information.
 * A **more flexible trigger system**, with each pipeline having any number of VCS or non-VCS triggers. This includes:
-** **Non-repo based triggers**: xref:webhooks#custom-webhooks[Custom webhooks] enable triggering builds from any system that can emit webhook events. Refer to our link:https://discuss.circleci.com/t/product-update-trigger-pipelines-from-anywhere-custom-webhooks/49864[community forum] for an example and known limitations.
+** **Non-repo based triggers**: xref:custom-webhooks#[Custom webhooks] enable triggering builds from any system that can emit webhook events. Refer to our link:https://discuss.circleci.com/t/product-update-trigger-pipelines-from-anywhere-custom-webhooks/49864[community forum] for an example and known limitations.
 ** **Cross-repo triggers**: Events in one repository can trigger builds on one or many other repositories.
 ** **More GitHub events as triggers**: Pipelines can be set up to run on events other than "push", including pull request events, with more powerful customization of trigger conditions. For full details, see the xref:github-trigger-event-options#[GitHub trigger event options] page.
 

jekyll/_cci2/webhooks-reference.adoc → jekyll/_cci2/outbound-webhooks-reference.adoc

@@ -5,7 +5,7 @@ contentTags:
   - Cloud
   - Server v4+
 ---
-= Webhooks reference
+= Outbound webhooks reference
 :page-layout: classic-docs
 :page-liquid:
 :icons: font

jekyll/_cci2/webhooks.adoc → jekyll/_cci2/outbound-webhooks.adoc

@@ -4,136 +4,19 @@ contentTags:
   - Cloud
   - Server v4+
 ---
-= Webhook integration
+= Outbound webhooks
 :page-layout: classic-docs
-:page-description: Use webhooks to integrate with third-party services and subscribe to CircleCI events
+:page-description: Use outbound webhooks to integrate with third-party services and subscribe to CircleCI events
 :icons: font
 :experimental:
 
-A webhook allows you to connect a platform (for example, CircleCI, an API you create yourself, or a third party service) to a stream of future _events_.
 
 Setting up an **outbound webhook** on CircleCI enables your third party service to receive information (referred to as _events_) from CircleCI, as they happen. This can help you avoid polling the API or manually checking the CircleCI web application for desired information.
 
-Setting up an inbound webhook (as a **custom webhook** trigger) on CircleCI enables a third party service to trigger a CircleCI pipeline. Any service that can send a webhook or make a `curl` request can trigger a CircleCI pipeline.
-
-== Custom webhooks
-
-NOTE: Custom webhooks are available for projects integrated via the GitHub App. Custom webhooks are not available on CircleCI server.
-
-Use **custom webhooks** to trigger a pipeline from anywhere that can emit a webhook or run a curl command.
-
-TIP: Custom webhooks are inbound to CircleCI and are used to trigger pipelines from other services. If you are looking for a way to have a CircleCI pipeline trigger a service, use an <<outbound-webhooks,outbound webhook>>.
-
-This section presents some use cases for CircleCI custom webhooks.
-
-=== Quickstart
-
-Follow these steps to set up and test a custom webhook trigger. Trigger from anywhere that can emit a webhook or run a curl command:
-
-include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
-
-. You can now test your custom webhook trigger with `curl`. To trigger your pipeline, copy and paste the following sample request and replace `<your-URL>` and `<your-secret>` with the URL and secret that you generated in the previous step:
-+
-NOTE: When triggering via `curl`, you must use a `POST` request with `content-type: application/json`.
-+
-[,shell]
-----
-curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'
-----
-
-See our link:https://discuss.circleci.com/t/trigger-pipelines-from-anywhere-inbound-webhooks-now-in-preview/49864[community forum] for more details or how to use this functionality with a link:https://discuss.circleci.com/t/re-build-automatically-when-new-image-is-available-on-dockerhub/50350[3rd party service like DockerHub].
-
-NOTE: Custom webhooks will not work with xref:contexts#security-group-restrictions[security group restrictions].  Additionally, the configuration file that is used for pipelines triggered by a custom webhook will only be visible in the CircleCI web app if the configuration file path is `.circleci/config.yml`.
-
-=== Example: Trigger one pipeline from another
-
-Use a custom webhook to configure one pipeline to trigger a second pipeline. For example, you might need to run a set of integration tests on a repository after you have made a change to a separate repository.
-
-For this example, assume you have two projects in separate repositories:
-
-TIP: You can also use this method to trigger one pipeline from another within the _same_ project.
-
-* Project A
-* Project B
-
-When a change is made to Project A, we want the full Project A configuration to be run, and then the Project B pipeline should be triggered. To achieve this, follow these steps:
-
-==== 1. Set up a custom webhook for Project B
-
-Navigate to Project B in the CircleCI web app and set up a custom webhook by following these steps:
-
-include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
-
-==== 2. Configure Project A to trigger Project B
-
-Navigate to Project A in the CircleCI web app and set up an environment variable. The value of the environment variable will be the secret from the custom webhook you just set up for Project B.
-
-TIP: As an alternative, you can add an environment variable using a xref:contexts#[context].
-
-. In the link:https://app.circleci.com/[CircleCI web app] select your organization.
-. Select **Projects** in the sidebar.
-. Find your project in the list, select the ellipsis (icon:ellipsis-h[]), and select **Project Settings**.
-. Select **Environment Variables** from the sidebar.
-. Select btn:[Add Environment Variable].
-. Give your environment variable a name, for example, `WEBHOOK_SECRET`.
-. Update your Project A configuration file with a step that will trigger a pipeline for Project B, for example (lines 13-16):
-+
-[,yaml]
-----
-version: 2.1
-
-jobs:
-  say-hello:
-    docker:
-      - image: cimg/base:stable
-    steps:
-      - checkout
-      - run:
-          name: example
-          command: echo "one step"
-
-      - run:
-          name: Kick off new pipeline
-          command: |
-              curl -X POST -H "content-type: application/json" "https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=${WEBHOOK_SECRET}"
-
-workflows:
-  say-hello-workflow:
-    jobs:
-      - say-hello
-----
-
-=== Example: Extract custom webhook payload data
-
-The custom webhook body is available by using the `pipeline.trigger_parameters.webhook.body` xref:variables#pipeline-values[pipeline value].
-
-The following example shows how you can use `jq` to extract values from the webhook payload into environment variables when you want to use them in your configuration.
-
-In this example the webhook body contains a property called `branch`. `jq` is installed and used to extract the `branch` value into an environment variable named `WEBHOOK_BRANCH`, which is then used in a GitHub clone command.
-
-TIP: The xref:configuration-reference#commands[command] configured in this example uses commands from the link:https://circleci.com/developer/orbs/orb/circleci/jq[jq] and link:https://circleci.com/developer/orbs/orb/circleci/github-cli[GitHub CLI] orbs.
-
-[,yaml]
-----
-commands:
-  shallow_clone:
-    description: Shallow Git Clone
-    steps:
-      - gh/setup:
-          token: "GITHUB_TOKEN"
-      - jq/install
-      - run:
-          name: Shallow Clone
-          command: |
-            WEBHOOK_BRANCH=$(echo '<< pipeline.trigger_parameters.webhook.body >>' | jq '.branch')
-            gh repo clone << pipeline.trigger_parameters.github_app.repo_url >> . -- --depth 10 --branch "$WEBHOOK_BRANCH"
-----
-
-== Outbound webhooks
-
+=== Introduction
 Use outbound webhooks to integrate your CircleCI builds with external services.
 
-For example, you could use <<outbound-webhooks>> to:
+For example, you could use outbound webhooks to:
 
 * Build a custom dashboard to visualize or analyze workflow/job events.
 * Send data to incident management tools (such as link:https://www.pagerduty.com[PagerDuty]).
@@ -162,7 +45,7 @@ To configure webhooks within the CircleCI app:
 . Fill out the webhook form (the table below describes the fields and their intent)
 . If your receiving API or third party service is set up, select *Test Ping Event* to send a test event.
 +
-NOTE: The test ping event has an abbreviated payload for ease of testing. See full examples for xref:webhooks-reference/#sample-webhook-payloads[sample webhook payloads] section of the webhooks reference.
+NOTE: The test ping event has an abbreviated payload for ease of testing. See full examples for xref:outbound-webhooks-reference/#sample-webhook-payloads[sample webhook payloads] section of the webhooks reference.
 
 [.table.table-striped]
 [cols=3*, options="header", stripes=even]
@@ -199,7 +82,7 @@ A webhook is sent using an HTTP POST to the URL that was registered when the web
 
 CircleCI expects the server that responds to a webhook will return a 2xx response code. If a non-2xx response is received, CircleCI will retry at a later time. If CircleCI does not receive a response to the webhook within a short period of time, CircleCI will assume that delivery has failed, and will retry at a later time. The timeout period is currently 10 seconds.
 
-Webhook requests may be duplicated. To deduplicate (prevent requests from being duplicated for a specific event), use the xref:webhooks-reference#common-top-level-keys[`id` property] in the webhook payload for identification.
+Webhook requests may be duplicated. To deduplicate (prevent requests from being duplicated for a specific event), use the xref:outbound-webhooks-reference#common-top-level-keys[`id` property] in the webhook payload for identification.
 
 If you have feedback about timeouts and retries, link:https://circleci.canny.io/webhooks[get in touch] with our team.
 
@@ -325,5 +208,5 @@ CircleCI currently offers outbound webhooks for the following events:
 [#next-steps]
 == Next steps
 
-* See the xref:webhooks-reference#[Webhooks reference] page for key definitions and sample payloads.
+* See the xref:outbound-webhooks-reference#[Webhooks reference] page for key definitions and sample payloads.
 * Follow the xref:webhooks-airtable#[Using webhooks with third party tools] tutorial.

jekyll/_cci2/triggers-overview.adoc

@@ -183,7 +183,7 @@ NOTE: When triggering via `curl`, you must use a `POST` request with `content-ty
 curl -X POST -H "content-type: application/json" 'https://internal.circleci.com/private/soc/e/<your-URL>?secret=<your-secret>'
 ----
 
-For more information on using custom and outbound webhooks, see the xref:webhooks#[Use webhooks to integrate with services] page. Also, see our link:https://discuss.circleci.com/t/trigger-pipelines-from-anywhere-inbound-webhooks-now-in-preview/49864[community forum] for more details or how to use this functionality with a link:https://discuss.circleci.com/t/re-build-automatically-when-new-image-is-available-on-dockerhub/50350[3rd party service like DockerHub].
+For more information on using custom and outbound webhooks, see the xref:custom-webhooks#[Custom webhooks] and xref:outbound-webhooks#[Outbound webhooks] pages. Also, see our link:https://discuss.circleci.com/t/trigger-pipelines-from-anywhere-inbound-webhooks-now-in-preview/49864[community forum] for more details or how to use this functionality with a link:https://discuss.circleci.com/t/re-build-automatically-when-new-image-is-available-on-dockerhub/50350[3rd party service like DockerHub].
 
 [NOTE]
 ====