Re-build automatically when new image is available on DockerHub


Software teams often have code that depends on a Docker image that is owned by a separate team within the same company. A common pain point with this setup is that staying up-to-date by using the latest image can come at the cost of instability if the newest version does not play nicely with the existing code.

To avoid this instability, CircleCI’s inbound webhooks gives users a way to “listen” for when a new image that you depend on is published so that your code can validate compatibility with the new image & get re-packaged with the new image if compatible.


This type of automation saves you and your team time by converting a tedious manual chore into an automated process. Any time there’s a new image to consume, you’ll immediately know if it can be incorporated or if it needs further investigation.


Navigate to → “Projects” → “Project Settings” → ”Triggers” → ”Add Trigger

Ensure “Inbound Webhook” is selected

Give the “inbound webhook” a human-readable “Source”, “Description”, and Configuration File Path. Click “Next” and write down the “Webhook URL” and “Secret” somewhere where they can accessed again.

In this example, we’re using a configuration file that is different than our typical “build-test-deploy” CI pipeline. In our repository, we still have a .circleci/config.yml that uses a pinned image version to “build-test-deploy” on every push, but we also have created a .circleci/listen_upstream_image.yml file that has a pipeline which:

  • Checks out code from repository
  • Pulls the new image that just got pushed
  • Authenticates the new image & performs an image scan
  • Rebuilds the repository using the new upstream image
  • Runs a set of tests against the newly built artifact
  • Sends a custom Slack notification to my team

Navigate to the DockerHub registry that your software depends on. Click on the “Webhooks” tab.

Paste the URL that you copied and stored earlier for your CircleCI inbound webhook.

Click “Create”. At this point, when a new image is pushed to that registry…

…a pipeline will run on CircleCI that runs the configuration that you specified:

Note: this functionality is only available to users who are using CircleCI’s GitHub App integration.