Skip to content

Commit 7609f5d

Browse files
yaningoyaningo
authored
Splitting webhook integration content over separate pages (#9379)
* Splitting webhook integration content over two separate pages * Streamlining content * More specific titles * Renaming reference page * Fixing xrefs * Fixing more xrefs * One more xref to fix * Removing unnecessary sentence
1 parent b5e360f commit 7609f5d

10 files changed

+150
-141
lines changed

‎jekyll/_cci2/custom-webhooks.adoc

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
contentTags:
3+
platform:
4+
- Cloud
5+
- Server v4+
6+
---
7+
= Custom webhooks
8+
:page-layout: classic-docs
9+
:page-description: Use webhooks to integrate with third-party services and subscribe to CircleCI events
10+
:icons: font
11+
:experimental:
12+
13+
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.
14+
15+
=== Introduction
16+
17+
NOTE: Custom webhooks are available for projects integrated via the GitHub App. Custom webhooks are not available on CircleCI server.
18+
19+
Use **custom webhooks** to trigger a pipeline from anywhere that can emit a webhook or run a curl command.
20+
21+
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].
22+
23+
=== Quickstart
24+
25+
26+
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:
27+
28+
include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
29+
30+
. 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:
31+
+
32+
NOTE: When triggering via `curl`, you must use a `POST` request with `content-type: application/json`.
33+
+
34+
[,shell]
35+
----
36+
curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'
37+
----
38+
39+
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].
40+
41+
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`.
42+
43+
44+
=== Example: Trigger one pipeline from another
45+
46+
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.
47+
48+
For this example, assume you have two projects in separate repositories:
49+
50+
TIP: You can also use this method to trigger one pipeline from another within the _same_ project.
51+
52+
* Project A
53+
* Project B
54+
55+
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:
56+
57+
==== 1. Set up a custom webhook trigger in Project B
58+
59+
Navigate to Project B in the CircleCI web app and set up a custom webhook by following these steps:
60+
61+
include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
62+
63+
==== 2. Configure Project A to trigger a pipeline in Project B
64+
65+
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.
66+
67+
TIP: As an alternative, you can add an environment variable using a xref:contexts#[context].
68+
69+
. In the link:https://app.circleci.com/[CircleCI web app] select your organization.
70+
. Select **Projects** in the sidebar.
71+
. Find your project in the list, select the ellipsis (icon:ellipsis-h[]), and select **Project Settings**.
72+
. Select **Environment Variables** from the sidebar.
73+
. Select btn:[Add Environment Variable].
74+
. Give your environment variable a name, for example, `WEBHOOK_SECRET`.
75+
. Update your Project A configuration file with a step that will trigger a pipeline for Project B, for example (lines 13-16):
76+
+
77+
[,yaml]
78+
----
79+
version: 2.1
80+
81+
jobs:
82+
say-hello:
83+
docker:
84+
- image: cimg/base:stable
85+
steps:
86+
- checkout
87+
- run:
88+
name: example
89+
command: echo "one step"
90+
91+
- run:
92+
name: Kick off new pipeline
93+
command: |
94+
curl -X POST -H "content-type: application/json" "https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=${WEBHOOK_SECRET}"
95+
96+
workflows:
97+
say-hello-workflow:
98+
jobs:
99+
- say-hello
100+
----
101+
102+
=== Example: Extract custom webhook payload data
103+
104+
The custom webhook body is available by using the `pipeline.trigger_parameters.webhook.body` xref:variables#pipeline-values[pipeline value].
105+
106+
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.
107+
108+
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.
109+
110+
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.
111+
112+
[,yaml]
113+
----
114+
commands:
115+
shallow_clone:
116+
description: Shallow Git Clone
117+
steps:
118+
- gh/setup:
119+
token: "GITHUB_TOKEN"
120+
- jq/install
121+
- run:
122+
name: Shallow Clone
123+
command: |
124+
WEBHOOK_BRANCH=$(echo '<< pipeline.trigger_parameters.webhook.body >>' | jq '.branch')
125+
gh repo clone << pipeline.trigger_parameters.github_app.repo_url >> . -- --depth 10 --branch "$WEBHOOK_BRANCH"
126+
----

‎jekyll/_cci2/github-apps-integration.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,7 @@ A subset of built-in environment variables are not available in GitHub-based pro
131131

132132
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:
133133

134-
* xref:webhooks#custom-webhooks[Custom webhooks]
134+
* xref:custom-webhooks#[Custom webhooks]
135135
* link:https://discuss.circleci.com/t/circleci-config-suggestions-bot/47918[CircleCI's config suggestions bot]
136136
* The ability to use xref:set-up-multiple-configuration-files-for-a-project#[multiple configuration files within one project]
137137

@@ -195,7 +195,7 @@ You cannot currently manage the connection with GitHub outside of the project se
195195
[#scheduled-pipelines]
196196
=== Scheduled pipelines
197197

198-
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.
198+
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.
199199

200200
[#build-forked-pull-requests]
201201
=== Build forked pull requests

‎jekyll/_cci2/github-integration.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -338,7 +338,7 @@ Key functionality enabled through the GitHub App integration includes the follow
338338
* The option to have **multiple pipelines in the same project**, each defined in its own YAML file.
339339
* 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.
340340
* A **more flexible trigger system**, with each pipeline having any number of VCS or non-VCS triggers. This includes:
341-
** **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.
341+
** **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.
342342
** **Cross-repo triggers**: Events in one repository can trigger builds on one or many other repositories.
343343
** **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.
344344

‎jekyll/_cci2/webhooks-reference.adoc renamed to ‎jekyll/_cci2/outbound-webhooks-reference.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ contentTags:
55
- Cloud
66
- Server v4+
77
---
8-
= Webhooks reference
8+
= Outbound webhooks reference
99
:page-layout: classic-docs
1010
:page-liquid:
1111
:icons: font

‎jekyll/_cci2/webhooks.adoc renamed to ‎jekyll/_cci2/outbound-webhooks.adoc

Lines changed: 7 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -4,136 +4,19 @@ contentTags:
44
- Cloud
55
- Server v4+
66
---
7-
= Webhook integration
7+
= Outbound webhooks
88
:page-layout: classic-docs
9-
:page-description: Use webhooks to integrate with third-party services and subscribe to CircleCI events
9+
:page-description: Use outbound webhooks to integrate with third-party services and subscribe to CircleCI events
1010
:icons: font
1111
:experimental:
1212

13-
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_.
1413

1514
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.
1615

17-
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.
18-
19-
== Custom webhooks
20-
21-
NOTE: Custom webhooks are available for projects integrated via the GitHub App. Custom webhooks are not available on CircleCI server.
22-
23-
Use **custom webhooks** to trigger a pipeline from anywhere that can emit a webhook or run a curl command.
24-
25-
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>>.
26-
27-
This section presents some use cases for CircleCI custom webhooks.
28-
29-
=== Quickstart
30-
31-
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:
32-
33-
include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
34-
35-
. 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:
36-
+
37-
NOTE: When triggering via `curl`, you must use a `POST` request with `content-type: application/json`.
38-
+
39-
[,shell]
40-
----
41-
curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'
42-
----
43-
44-
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].
45-
46-
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`.
47-
48-
=== Example: Trigger one pipeline from another
49-
50-
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.
51-
52-
For this example, assume you have two projects in separate repositories:
53-
54-
TIP: You can also use this method to trigger one pipeline from another within the _same_ project.
55-
56-
* Project A
57-
* Project B
58-
59-
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:
60-
61-
==== 1. Set up a custom webhook for Project B
62-
63-
Navigate to Project B in the CircleCI web app and set up a custom webhook by following these steps:
64-
65-
include::../_includes/partials/pipelines-and-triggers/custom-webhook-setup.adoc[]
66-
67-
==== 2. Configure Project A to trigger Project B
68-
69-
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.
70-
71-
TIP: As an alternative, you can add an environment variable using a xref:contexts#[context].
72-
73-
. In the link:https://app.circleci.com/[CircleCI web app] select your organization.
74-
. Select **Projects** in the sidebar.
75-
. Find your project in the list, select the ellipsis (icon:ellipsis-h[]), and select **Project Settings**.
76-
. Select **Environment Variables** from the sidebar.
77-
. Select btn:[Add Environment Variable].
78-
. Give your environment variable a name, for example, `WEBHOOK_SECRET`.
79-
. Update your Project A configuration file with a step that will trigger a pipeline for Project B, for example (lines 13-16):
80-
+
81-
[,yaml]
82-
----
83-
version: 2.1
84-
85-
jobs:
86-
say-hello:
87-
docker:
88-
- image: cimg/base:stable
89-
steps:
90-
- checkout
91-
- run:
92-
name: example
93-
command: echo "one step"
94-
95-
- run:
96-
name: Kick off new pipeline
97-
command: |
98-
curl -X POST -H "content-type: application/json" "https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=${WEBHOOK_SECRET}"
99-
100-
workflows:
101-
say-hello-workflow:
102-
jobs:
103-
- say-hello
104-
----
105-
106-
=== Example: Extract custom webhook payload data
107-
108-
The custom webhook body is available by using the `pipeline.trigger_parameters.webhook.body` xref:variables#pipeline-values[pipeline value].
109-
110-
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.
111-
112-
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.
113-
114-
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.
115-
116-
[,yaml]
117-
----
118-
commands:
119-
shallow_clone:
120-
description: Shallow Git Clone
121-
steps:
122-
- gh/setup:
123-
token: "GITHUB_TOKEN"
124-
- jq/install
125-
- run:
126-
name: Shallow Clone
127-
command: |
128-
WEBHOOK_BRANCH=$(echo '<< pipeline.trigger_parameters.webhook.body >>' | jq '.branch')
129-
gh repo clone << pipeline.trigger_parameters.github_app.repo_url >> . -- --depth 10 --branch "$WEBHOOK_BRANCH"
130-
----
131-
132-
== Outbound webhooks
133-
16+
=== Introduction
13417
Use outbound webhooks to integrate your CircleCI builds with external services.
13518

136-
For example, you could use <<outbound-webhooks>> to:
19+
For example, you could use outbound webhooks to:
13720

13821
* Build a custom dashboard to visualize or analyze workflow/job events.
13922
* 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:
16245
. Fill out the webhook form (the table below describes the fields and their intent)
16346
. If your receiving API or third party service is set up, select *Test Ping Event* to send a test event.
16447
+
165-
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.
48+
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.
16649

16750
[.table.table-striped]
16851
[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
19982

20083
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.
20184

202-
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.
85+
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.
20386

20487
If you have feedback about timeouts and retries, link:https://circleci.canny.io/webhooks[get in touch] with our team.
20588

@@ -325,5 +208,5 @@ CircleCI currently offers outbound webhooks for the following events:
325208
[#next-steps]
326209
== Next steps
327210

328-
* See the xref:webhooks-reference#[Webhooks reference] page for key definitions and sample payloads.
211+
* See the xref:outbound-webhooks-reference#[Webhooks reference] page for key definitions and sample payloads.
329212
* Follow the xref:webhooks-airtable#[Using webhooks with third party tools] tutorial.

‎jekyll/_cci2/triggers-overview.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ NOTE: When triggering via `curl`, you must use a `POST` request with `content-ty
183183
curl -X POST -H "content-type: application/json" 'https://internal.circleci.com/private/soc/e/<your-URL>?secret=<your-secret>'
184184
----
185185

186-
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].
186+
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].
187187

188188
[NOTE]
189189
====

0 commit comments

Comments
 (0)