Custom webhooks (formerly known as “inbound webhooks”)
Trigger a pipeline from any location that can emit a webhook or run a curl request. Validate changes from external tools such as model/dataset registries
Creating a webhook trigger
-
In the CircleCI web app, navigate to “Project Settings” >> “Pipelines”. If there is already a pipeline set up, proceed to step 3 below. Else: click “Set Up Pipeline” >> “Connect”. Install CircleCI’s GitHub App into your GitHub organization (you can choose whether to grant access to all repositories or a subset of repositories).
-
Name the pipeline and select the repository where the CircleCI YML configuration file is stored. Enter the file path (include the
.circleci
directory). The file path can be something other than.circleci/config.yml
, for
example,.circleci/webhook.yml
. Save the pipeline.
-
Go to “Project Settings” >> “Triggers” >> “Add trigger”
-
Select “Custom Webhook” >> “Next”
- Give the trigger a name & description and select the pipeline that you created in step 1 above. Save the trigger.
- Store the webhook URL & secret.
Now every time the custom webhook’s URL is pinged, a pipeline will be triggered using the CircleCI configuration file that you specified in the file path.
Example of triggering from a curl command:
curl -X POST -H "content-type: application/json" 'https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=insertSecret'
You must use a POST
command with content-type: application/json
. Always include the secret in the URL when calling it.
Example of using an custom webhook to make a pipeline trigger a pipeline from another project:
In this example, when project A finishes running a pipeline, we will enable project B to automatically run a pipeline as well (for example, if you’d like to run a set of integration tests on a repo after you’ve made a change to a separate repo).
In project B, set up an custom webhook in Project Settings > Triggers. Copy the “Secret” and add it as an environment variable in Project A’s Project Settings > Environment Variables (ie.WEBHOOK_SECRET_2
).
In project A’s configuration file, call the custom webhook’s “Webhook URL” via a curl command like the below example with the secret as an environment variable.
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_2}"
workflows:
say-hello-workflow:
jobs:
- say-hello
At this point, every time project A runs a pipeline, project B will subsequently run a pipeline as well.
This functionality is also available to orgs that integrate with CircleCI’s GitHub OAuth App, read more about that here.
Known Limitations
Contexts that are restricted to a GitHub security group will not work if you are using custom webhooks.
The configuration file that was 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
.