---
title: "Jenkins Plugin | WebhookRelay"
meta:
  "og:description": "Receive GitHub, GitLab and Bitbucket webhooks in Jenkins without a public IP using the native Webhook Relay plugin."
  "og:title": "Jenkins Plugin"
  description: "Receive GitHub, GitLab and Bitbucket webhooks in Jenkins without a public IP using the native Webhook Relay plugin."
---

![Stripes](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/stripes.svg)

Documentation

**Fundamentals**

# **Jenkins Plugin**

Receive GitHub, GitLab and Bitbucket webhooks in Jenkins without a public IP using the native Webhook Relay plugin.

The **Webhook Relay Jenkins plugin** lets Jenkins receive webhooks from GitHub, GitLab and Bitbucket **without exposing Jenkins to the public internet** — no public IP, no reverse proxy, no inbound firewall rules. The plugin opens an outbound connection to a Webhook Relay **bucket** and forwards each webhook it receives to the matching Jenkins endpoint (`/github-webhook/`, `/bitbucket-hook/`, …), so your SCM can trigger builds even when Jenkins runs on a private network, behind a NAT, or on your laptop.

Unlike running the `relay` CLI as a separate agent, the plugin runs **inside Jenkins** — there is nothing else to install or keep alive. And because delivery goes through a bucket (the forwarding feature, not a tunnel), **every webhook is recorded on the bucket's logs page** together with the response Jenkins returned, which makes debugging deliveries trivial.

![GitHub to Jenkins without public IP](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/github-webhooks-jenkins.png)

## [How it works](#how-it-works)

```
GitHub / GitLab / Bitbucket
        │  (webhook)
        ▼
https://<your-bucket>.hooks.webhookrelay.com      ← public URL you paste into the SCM
        │
        ▼
   Webhook Relay bucket  ──────────────►  logs page (every request + Jenkins response)
        │  (outbound WebSocket opened by the plugin)
        ▼
   Jenkins  →  /github-webhook/  →  build triggered
```

1. The plugin authenticates with your API token and **subscribes** to a bucket over a persistent outbound WebSocket. No inbound ports are opened on Jenkins.
2. A webhook hits the bucket's public input URL and Webhook Relay streams it down the socket.
3. The plugin replays the request against the Jenkins endpoint for your SCM and reports the response back to the bucket log.

## [Requirements](#requirements)

- Jenkins 2.479.1 or newer (Java 17 or 21)
- A free [Webhook Relay](https://webhookrelay.com) account and an [API token](https://my.webhookrelay.com/tokens)

## [1. Install the plugin](#_1-install-the-plugin)

From **Manage Jenkins → Plugins → Available**, search for **Webhook Relay** and install it.

To install a downloaded build manually, go to **Manage Jenkins → Plugins → Advanced settings → Deploy Plugin** and upload the `webhook-relay.hpi` file:

![Deploy the Webhook Relay plugin](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/plugin-01-install-deploy-plugin.png)

After restarting, the plugin shows up under **Installed plugins**:

![Webhook Relay plugin installed](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/plugin-02-installed-plugin.png)

## [2. Configure the connection](#_2-configure-the-connection)

Open **Manage Jenkins → System** and scroll to the **Webhook Relay** section:

1. Enter your **API Key** and **API Secret** from the [tokens page](https://my.webhookrelay.com/tokens).
2. Enter a **Bucket name** (for example `jenkins-plugin`). It can be an existing bucket or a new name — the plugin will create it for you.
3. Pick your **SCM Webhook Preset** (GitHub, GitLab, Bitbucket or Generic Webhook Trigger).
4. Tick **Enable** and click **Save**.

![Configure the Webhook Relay plugin](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/plugin-03-config-subscribed.png)

When connected, **Connection Status** reads **✔ Subscribed**. Use **Test Connection** to verify your credentials at any time.

## [3. Get your webhook URL](#_3-get-your-webhook-url)

Click **Get Webhook URL**. The plugin resolves the bucket's public input URL (creating the bucket if it doesn't exist yet) and shows the value to paste into your repository:

![Resolve the public webhook URL](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/plugin-04-get-webhook-url.png)

Add it as a webhook in your repository settings:

| SCM | Where to paste the URL |
| --- | --- |
| GitHub | _Settings → Webhooks → Add webhook → Payload URL_ (content type `application/json`) |
| GitLab | _Settings → Webhooks → URL_ |
| Bitbucket | _Repository settings → Webhooks → Add webhook → URL_ |

That's the only change in your SCM — you point the webhook at the Webhook Relay URL instead of at Jenkins directly.

## [4. Trigger a build](#_4-trigger-a-build)

Configure the Jenkins job exactly as you would for a public Jenkins. For GitHub, that means a Pipeline or Freestyle job with a Git SCM and **GitHub hook trigger for GITScm polling** enabled (`githubPush()` in a declarative pipeline). For GitLab and Bitbucket, enable the corresponding hook trigger; for everything else, use the [Generic Webhook Trigger](https://plugins.jenkins.io/generic-webhook-trigger/).

Now push a commit. The webhook travels GitHub → bucket → plugin → `/github-webhook/`, and the build starts:

![Build triggered by a GitHub push through Webhook Relay](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/images/tutorials/jenkins/plugin-05-build-triggered.png)

## [5. Inspect deliveries](#_5-inspect-deliveries)

Open your bucket on [my.webhookrelay.com/buckets](https://my.webhookrelay.com/buckets). Each webhook is listed with its method, status and the response Jenkins returned — a `sent` status with response status `200` means Jenkins accepted the webhook.

## [Try it with Docker](#try-it-with-docker)

The plugin repository ships a ready-to-run demo (Jenkins + Configuration as Code):

```
git clone https://github.com/jenkinsci/webhook-relay-plugin
cd webhook-relay-plugin
mvn -q clean package
docker compose -f demo/docker-compose.yml up --build   # Jenkins on http://localhost:8095
```

Then follow the steps above.

## [Prefer the CLI agent?](#prefer-the-cli-agent)

If you'd rather run a standalone forwarding agent instead of installing a plugin, see [Jenkins and GitHub](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/docs/tutorials/cicd/jenkins-github/) and [Jenkins and Bitbucket](https://webhookrelay.com/docs/tutorials/cicd/jenkins-plugin/docs/tutorials/cicd/jenkins-bitbucket/), which use the `relay` CLI. The plugin and the CLI agent both deliver through buckets, so the logs and SCM setup are identical — the plugin just removes the separate agent process.

Did this page help you?