Custom webhooks (formerly known as “inbound webhooks”) are now also available to orgs that integrate with CircleCI’s GitHub OAuth App
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 and choose whether to grant access to all repositories or a subset of repositories (CircleCI organizations that use the GitHub OAuth App can also install the GitHub App, read more here).
-
Name the pipeline and select the repository where the CircleCI YML configuration file is stored. Enter the file path (include the
.circlecidirectory). 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.