Jenkins Webhooks

A pipeline that waits for someone to press a button defeats the purpose of automation. Webhooks let your code host tell Jenkins the instant something happens, such as a push or a pull request. Jenkins reacts within seconds and starts the right job.

The Layman's View

Imagine waiting for a parcel. Polling means walking to the front door every five minutes to check. A webhook means the courier rings your doorbell the moment the parcel arrives. The doorbell saves effort and tells you at the right moment.

Polling Versus Webhooks

POLLING
 Jenkins ---"Any change?"---> Git     (every 5 minutes)
 Jenkins <--"No"----------- Git
 Jenkins ---"Any change?"---> Git
 Jenkins <--"Yes"---------- Git     (delay up to 5 minutes)

WEBHOOK
 Developer pushes code
        |
        v
      Git ---"Change happened!"---> Jenkins ---> build starts at once

Point	Polling	Webhook
Delay	Up to the poll interval	Near instant
Server load	Constant checks	Only on real events
Setup	Simple	Needs network access from Git to Jenkins

Setting Up a GitHub Webhook

On the Jenkins Side

1. Install the GitHub plugin.
2. Open the job configuration.
3. Under Build Triggers, tick GitHub hook trigger for GITScm polling.
4. Save the job.

Pipeline users can declare the trigger in the Jenkinsfile instead:

pipeline {
    agent any
    triggers {
        githubPush()
    }
    stages {
        stage('Build') {
            steps { sh 'mvn -B package' }
        }
    }
}

On the GitHub Side

1. Open the repository and select Settings, then Webhooks.
2. Click Add webhook.
3. Enter the payload URL: https://your-jenkins.example.com/github-webhook/ with the trailing slash.
4. Set the content type to application/json.
5. Choose Just the push event, or select individual events.
6. Save the webhook and check for a green tick in Recent Deliveries.

How the Message Travels

 Developer
    | git push
    v
 GitHub repository
    | HTTPS POST with JSON payload
    v
 https://your-jenkins.example.com/github-webhook/
    |
    v
 Jenkins finds jobs that use this repository
    |
    v
 Matching jobs start a build

Network Requirements

GitHub must reach your Jenkins URL over the internet. A Jenkins server hidden inside a private network cannot receive the message. Three common solutions exist:

• Place a reverse proxy such as Nginx in front of Jenkins and open only the webhook path.
• Use a relay service that forwards messages into the private network.
• Fall back to polling for repositories that cannot reach the server.

Always serve the endpoint over HTTPS so that outsiders cannot read the payload.

Generic Webhook Trigger

Not every tool is GitHub. The Generic Webhook Trigger plugin accepts messages from GitLab, Bitbucket, Jira, or your own scripts. It reads values from the JSON body and passes them to the pipeline as variables.

pipeline {
    agent any
    triggers {
        GenericTrigger(
            genericVariables: [
                [key: 'BRANCH', value: '$.ref']
            ],
            token: 'my-secret-token',
            causeString: 'Triggered by webhook'
        )
    }
    stages {
        stage('Show') {
            steps { echo "Branch ref: ${BRANCH}" }
        }
    }
}

The sender calls https://your-jenkins.example.com/generic-webhook-trigger/invoke?token=my-secret-token to start the job.

Securing Webhooks

Use a Secret Token

Anyone who learns the URL can start builds. A token or a shared secret blocks strangers.

Limit the Events

Send only the events your pipeline needs. Fewer events mean fewer needless builds.

Restrict Source Addresses

Firewall rules can accept traffic only from the code host's published address ranges.

Testing and Troubleshooting

Symptom	Check
GitHub shows a red cross for delivery	Confirm the URL, HTTPS certificate, and trailing slash
Delivery succeeds but no build starts	Verify the job's repository URL matches the pushed repository exactly
Response code 403	Review proxy rules and Jenkins security settings
Builds start twice	Remove polling when the webhook already handles triggering

GitHub keeps a log of each delivery with the request and the response. Open Recent Deliveries and click Redeliver to replay a message while you fix the setup.

Choosing the Right Approach

• Pick webhooks when Jenkins is reachable and speed matters.
• Pick polling when networks block incoming traffic.
• Pick a schedule for jobs that run nightly regardless of code changes.

A working webhook makes the pipeline feel alive: push a commit, watch the build appear, and receive results before your coffee cools.