Trigger pipelines from anywhere: inbound webhooks now in preview

Now in preview: 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

Note: Inbound webhooks are currently only available to customers connecting GitHub to CircleCI via the GitHub App.

We’re always looking for feedback so feel free to add comments to this post or email our team directly at sebastian@circleci.com

Creating a webhook trigger

  1. Go to Project Settings >> Triggers >> Add trigger

  2. Select “Inbound Webhook” and then “Next”

  3. Input your “Trigger Source” name and description. Input a file path to a CircleCI configuration file that you want to run when this webhook is called and click “Save”. This does not have to be the default .circleci/config.yml file path, it can be any file path in the repository.

  4. Get the webhook URL and secret (you will copy this webhook URL into your respective trigger source or tool)

  5. Go to the external source of change from which you are accepting the webhook event (e.g. Datadog, Docker, Hugging Face) and set up the webhook there, like in the example below. If the source has a “secret” field, leave it blank and include the secret in the webhook URL.

Now every time the inbound 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.

Example of using an inbound 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 inbound 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 inbound 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.

Known Limitations

At this time, only the configuration file from the default branch will be used. Any code that is checked out from the repository will be from the default branch unless a custom checkout step is used.

2 Likes

I don’t want to use Hugging Face.

I’m looking for a replacement for the “trigger a pipeline” API.

The web app advertises that I can trigger a pipeline from anywhere that can run a curl command.

What curl command do I need to use?

I set up the inbound webhook follwing your instructions.

I use a curl command like this to test the webhook:

curl -G "https://internal.circleci.com/private/soc/e/bb29a2a6-5673-403d-baef-5b46f59f7332" -d @/tmp/webhooksecret

I get this error.

{"Status":"Endpoint not found"}

Is something missing?

curl -X POST -H "content-type: application/json" 'https://internal.circleci.com/private/soc/e/6ccfca1c-5ed6-4dcf-96ca-374969d6edcb?secret=insertSecret'

Worked for me. I can get this post updated with that example.

You may want to take the time to change the DNS name used for this service. ‘internal’ is not the best name to assign to a public service and so will cause a lot of misunderstandings going forwards.

1 Like

Hey there

I’m curious on the restriction to “Github App” only right now…

Looking at the list of missing features for the “Github App” integration (no manual trigger and no schedules!!!), we’re not in a position to transition right now. But having the ability to trigger pipelines via a Webhook would be extremely useful.

Is this feature likely to be available to Github OAuth users? Or when will the Github App integration be brought up to feature parity?

Thanks

@fatmcgav The feature will eventually be available to all CircleCI users, I unfortunately don’t have a timeline to share though for when that will happen.

Manual triggers we expect to be possible within the next ~3 months for users on the GitHub App integration. The timeline for the ability to schedule builds is still TBD.

I’m curious, what is your use case for using inbound webhooks? Any chance you’d be open to talking to our User Research team for 45 minutes about this and a new prototype to simplify setting up inbound webhooks? We offer compensation in the form of a Tremendous gift card, email me at sebastian@circleci.com if you’re interested, we’d love to hear from you.