Go to Application

Custom webhooks

3 months ago · 10 min read

Cloud Server v4+

Contribute

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

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.

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

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis next to your project and select Project Settings.

You can also access project settings from each project overview page using the Settings button.
Select Project Setup in the sidebar.

If there is already a GitHub App pipeline set up that you want to trigger with your custom webhook, proceed to the Triggers step below (step 5). If not, select Add Pipeline. You can find guidance on setting up a pipeline in the Pipelines overview and setup page.

If you have not installed the CircleCI GitHub App into your GitHub organization you will be prompted to do so. Installing the GitHub App is a one-time step that can be done by an organization admin. Once installed, further GitHub App pipelines can be set up without this installation step. For a detailed guide to using both OAuth and GitHub App integrations, see the Using the CircleCI GitHub App in an OAuth organization page. If you run into issues when installing the GitHub App, for example, App looks installed on GitHub, but does not show up on CircleCI, submit a request through this form.

Select Custom webhook + at the bottom of the pipeline box.
Enter a descriptive name for the webhook event.
Enter the name of the event source for the trigger. For example, if you are setting up a custom webhook to run pipelines on events from Datadog, enter "Datadog" here.
Enter the branch to use to fetch your config file and checkout your code when a Custom Webhook is received.
Select Save.
You will see a webhook endpoint URL and secret. You can use these to set up your webhook trigger from your external source. Copy the Webhook URL and use it in your trigger source appended with the secret.

The secret will not be shown again so be sure to copy the URL before clicking Done.
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:

When triggering via curl, you must use a POST request with content-type: application/json.
```
curl -X POST -H "content-type: application/json" '<your-URL>?secret=<your-secret>'
```

See our community forum for more details or how to use this functionality with a 3rd party service like DockerHub.

Custom webhooks will not work with 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:

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:

In the CircleCI web app, select your org from the org cards on your user homepage.
Select Projects from the sidebar and locate your project from the list. You can use the search to help.
Select the ellipsis next to your project and select Project Settings.

You can also access project settings from each project overview page using the Settings button.
Select Project Setup in the sidebar.

Select Custom webhook + at the bottom of the pipeline box.
Enter a descriptive name for the webhook event.
Enter the name of the event source for the trigger. For example, if you are setting up a custom webhook to run pipelines on events from Datadog, enter "Datadog" here.
Enter the branch to use to fetch your config file and checkout your code when a Custom Webhook is received.
Select Save.
You will see a webhook endpoint URL and secret. You can use these to set up your webhook trigger from your external source. Copy the Webhook URL and use it in your trigger source appended with the secret.

The secret will not be shown again so be sure to copy the URL before clicking Done.

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.

As an alternative, you can add an environment variable using a context.

In the CircleCI web app select your organization.
Select Projects in the sidebar.
Find your project in the list, select the ellipsis , and select Project Settings.
Select Environment Variables from the sidebar.
Select 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):

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

The command configured in this example uses commands from the jq and GitHub CLI orbs.

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"

[path]

[title]

Custom webhooks

Introduction

Quickstart

Example: Trigger one pipeline from another

1. Set up a custom webhook trigger in Project B

2. Configure Project A to trigger a pipeline in Project B

Example: Extract custom webhook payload data