Jenkins Webhook Proxy

The webhook proxy service allows to trigger Jenkins pipelines. Further, it automatically creates pipelines that do not exist yet and can delete pipelines that are no longer needed.

One instance of the webhook proxy runs in every <project>-cd namespace next to the Jenkins instance.



Accepts webhooks from BitBucket and forwards them to the corresponding Jenkins pipeline (which is determined based on the component param and the branch name). If there is no corresponding pipeline yet, it will be created on the fly (by creating a BuildConfig in OpenShift which is synced to Jenkins via the OpenShift plugin). Once a branch is deleted or a pull request declined/merged, the corresponding Jenkins pipeline is deleted.

POST /build

Accepts a payload of the following form:

    "branch": "foo",
    "repository": "repository",
    "env": [
          "name": "FOO_BAR",
          "value": "baz"
    "project": "bar"

Important: In order to avoid conflicts between pipelines created/triggered via BitBucket and pipelines created/triggered via /build, most likely you’d want to pass a component name to /build, like so: /build?component=foo, see the next section.

Also note that the project field is optional, and restricted to the project of the webhook proxy and opendevstack by default (but can be customized via ALLOWED_EXTERNAL_PROJECTS).


Both / and /build accept the following query parameters. They are offered as query parameters only because otherwise they could not be adjusted for BitBucket webhooks.

Variable Description


The path to the Jenkinsfile. By default, the Jenkinsfile is assumed to be in the root of the repository, therefore this value defaults to simply Jenkinsfile.


The component part of the pipeline name. If not given, the pipeline name is created from the repository and the branch.


Adding a webhook in BitBucket

The provisioning app sets up one webhook per repository by default. It is possible to create webhooks manually as well, e.g. to add more than one webhook (likely differentiated by the component param then).

To manually create a webhook, go to "Repository Settings > Webhooks" and click on "Create webhook". Fill in the following:

  • Name: Jenkins (or similar, value is only serves as a description)

  • URL: route to the webhook proxy instance, followed by the trigger_secret, e.g. The secret can be retrieved in the OpenShift console in your *-cd namespace (in this example foo-cd) under "Resources > Secrets > webhook-proxy".

  • Secret: leave blank

  • Under "Repository events", select Push. Under "Pull request events", select Merged and Declined

Now you can verify by clicking "Test connection". Afterwards, save your changes. The next pushed commit should automatically send a request to the webhook proxy and start a pipeline in Jenkins.

Customizing the behaviour of the webhook proxy

The following environment variables can be set on the DeploymentConfig and are read by the webhook proxy:

Variable Description


Comma-separated list of handled Bitbucket events. Defaults to repo:refs_changed,pr:declined,pr:merged,pr:deleted.


Comma-separated list of Bitbucket change refs. Defaults to BRANCH, which means tags do not create pipelines nor forward to them. If you want this to happen, specify e.g. BRANCH,TAG.


Comma-separated list of external projects which the Webhook Proxy can deal with. For security reasons, by default the webhook proxy allows only its own project and the opendevstack project to be passed as a project parameter.


Defaults to openshift.default.svc.cluster.local. Usually does not need to be modified.


Comma-separated list of branches which pipelines should not be removed after they have been merged. Use either exact branch names, branch prefixes (e.g. feature/) or * for all branches. Defaults to: master,develop,production,staging,release/.


The base URL of the repository (e.g. your BitBucket host). This variable is set by the OpenShift template from which the DeploymentConfig is created and usually does not need to be modified.


The secret which protects the pipeline to be executed from outside. This variable is set by the OpenShift template from which the DeploymentConfig is created and usually does not need to be modified.


See the Makefile targets.