Jenkins- webhook integration

DevOps Hands-On Lab

How to Configure GitHub Webhooks to Trigger Jenkins Builds Automatically

Configure GitHub to automatically notify Jenkins whenever code is pushed to a repository.

Lab Objective
By the end of this lab, every push to your GitHub repository will automatically trigger a Jenkins build. You will no longer need to manually click Build Now after every code change.

What is a Webhook?

A webhook is a push-based notification mechanism. Instead of Jenkins repeatedly checking GitHub to determine whether code has changed, GitHub sends an HTTP POST request to Jenkins immediately after a configured event occurs.

Developer
    |
    | git push
    v
GitHub Repository
    |
    | Webhook HTTP POST
    v
Jenkins
    |
    | Automatic Build
    v
Build / Test / Scan / Deploy

Ways Jenkins Jobs Can Be Triggered

Jenkins jobs can be started in several ways. Three common approaches are:

1. Manual Build – a user clicks Build Now.
2. Poll SCM – Jenkins periodically checks the source repository for changes.
3. Webhook – GitHub immediately notifies Jenkins when a repository event occurs.

Jenkins can also be triggered from other systems and integrations such as chat tools, APIs, schedulers, upstream jobs, and pipelines. This lab focuses specifically on the GitHub webhook push mechanism.

Poll SCM vs GitHub Webhook

Poll SCM	GitHub Webhook
Jenkins checks GitHub.	GitHub contacts Jenkins.
Pull mechanism.	Push mechanism.
Runs on a schedule.	Runs when the event happens.
Can create unnecessary repository polling.	More event-driven and immediate.

Prerequisites

Before beginning this lab, make sure you have:

• A GitHub account.
• A GitHub repository containing your application code.
• A running Jenkins server.
• A Jenkins job already configured to clone your GitHub repository.
• Git installed/configured in Jenkins.
• The GitHub repository URL configured under Jenkins Source Code Management > Git.
• GitHub credentials configured in Jenkins if the repository is private.
• A Jenkins URL that GitHub can reach over the network.

Important: A URL such as http://localhost:8080 cannot be used by GitHub. GitHub must be able to reach your Jenkins server from the internet or through an appropriate webhook relay/network configuration.

Architecture for This Lab

Developer
    |
    | git add / git commit / git push
    v
+----------------------+
|      GitHub Repo     |
+----------+-----------+
           |
           | Push Event
           | Webhook
           v
+----------------------+
|       Jenkins        |
+----------+-----------+
           |
           | Checkout Source
           v
+----------------------+
| Build / Test / Scan  |
+----------+-----------+
           |
           v
       Deployment

Step 1 – Install the GitHub Plugin in Jenkins

Log in to Jenkins and navigate to:

Manage Jenkins → Plugins

Depending on the Jenkins version, you may see tabs such as Available plugins and Installed plugins.

1. Open Available plugins.
2. Search for GitHub.
3. Select the GitHub plugin.
4. Install the plugin.

Also verify that the normal Git-related Jenkins plugins are available, including:

• Git plugin
• Git client plugin
• GitHub plugin
• Credentials plugin

Step 2 – Verify the Jenkins Job Uses the GitHub Repository

Open the Jenkins job that should run when code is pushed.

Jenkins Dashboard → Your Job → Configure

Under Source Code Management, select:

Git

Enter your GitHub repository URL:

https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git

Example:

https://github.com/devopstreams/MyWebApp.git

If the repository is private, select your GitHub credentials.

For HTTPS authentication, a Jenkins credential may look like:

Kind: Username with password
Username: YOUR_GITHUB_USERNAME
Password: YOUR_GITHUB_PERSONAL_ACCESS_TOKEN

Security: Do not enter your normal GitHub password in Jenkins and never commit a Personal Access Token to source control.

Under Branches to build, use the branch your class/project is using. For a repository using the standard main branch:

*/main

Step 3 – Configure the Jenkins GitHub Build Trigger

Remain inside the Jenkins job configuration page and locate:

Build Triggers

Enable:

☑ GitHub hook trigger for GITScm polling

In older Jenkins GitHub plugin versions, this option was called Build when a change is pushed to GitHub. The current GitHub plugin calls it GitHub hook trigger for GITScm polling.

Disable Poll SCM

If you previously enabled:

☐ Poll SCM

uncheck it for this lab.

The goal is to use GitHub as the event source instead of making Jenkins continuously poll GitHub.

Click Save.

Step 4 – Determine the Jenkins Webhook URL

The Jenkins GitHub plugin receives GitHub events at:

JENKINS_BASE_URL/github-webhook/

For example, if Jenkins is available at:

http://54.123.45.67:8080

your webhook URL becomes:

http://54.123.45.67:8080/github-webhook/

If Jenkins is behind HTTPS and a domain:

https://jenkins.example.com/github-webhook/

Important: Use /github-webhook/. The trailing slash is recommended and avoids unnecessary webhook endpoint problems.

Step 5 – Make Sure GitHub Can Reach Jenkins

GitHub must be able to make an inbound HTTP/HTTPS request to the Jenkins webhook endpoint.

If Jenkins is running on AWS EC2 for a training lab, verify:

• The EC2 instance is running.
• The Jenkins service is running.
• The correct public IP address or DNS name is being used.
• The instance firewall/security rules allow the required inbound traffic.
• Any reverse proxy, load balancer, or firewall forwards requests to Jenkins correctly.

Production security note: Do not treat exposing the entire Jenkins administration interface directly to the public internet on port 8080 as a production architecture. Prefer HTTPS and a properly secured reverse proxy/load balancer or another controlled ingress mechanism.

Step 6 – Create the Webhook in GitHub

Open the repository in GitHub.

GitHub Repository → Settings → Webhooks → Add webhook

You must have repository owner or administrator permissions to create a repository webhook.

Payload URL

Enter your Jenkins GitHub webhook endpoint:

http://YOUR-JENKINS-PUBLIC-IP:8080/github-webhook/

Example:

http://54.123.45.67:8080/github-webhook/

Content type

Select:

application/json

Secret

GitHub allows an optional webhook secret. For a simple classroom lab using the standard Jenkins GitHub plugin in manual webhook mode, you may leave this blank unless you have separately configured secret validation.

In production integrations, webhook secrets are strongly recommended where the receiver supports validating them.

Which events would you like to trigger this webhook?

Select:

◉ Just the push event

For this lab, we only need GitHub to notify Jenkins when code is pushed.

Active

Make sure:

☑ Active

Finally, click:

Add webhook

Step 7 – Verify GitHub's Initial Ping

When the webhook is created, GitHub sends a ping event to the webhook URL.

Return to:

Repository → Settings → Webhooks

Open the webhook and look at:

Recent deliveries

A successful request indicates that GitHub was able to contact the Jenkins webhook endpoint.

Step 8 – Test the Webhook

Do not click Build Now. The point of this lab is to prove that GitHub can trigger Jenkins automatically.

Option A – Make a Change Directly in GitHub

1. Open the repository.
2. Edit a file such as README.md.
3. Make a small change.
4. Commit the change to main.

Option B – Push from Your Local Machine

git clone https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.git
cd YOUR-REPOSITORY

echo "Testing Jenkins GitHub webhook" >> README.md

git add .
git commit -m "Test Jenkins GitHub webhook"
git push origin main

Step 9 – Verify the Automatic Jenkins Build

Go back to Jenkins:

Jenkins Dashboard → Your Job

A new build should have started automatically.

The flow should now be:

Code Change
    |
    v
git commit
    |
    v
git push
    |
    v
GitHub
    |
    | push webhook
    v
Jenkins
    |
    v
Automatic Build

If your Jenkins job also contains Maven, SonarQube, artifact packaging, or deployment steps, those stages continue as normal after the webhook starts the job.

Step 10 – Check Jenkins Console Output

Open the new Jenkins build and select:

Console Output

Verify that Jenkins:

• Detected the GitHub-triggered change.
• Checked out the repository.
• Built the expected branch.
• Completed the configured build steps.

Troubleshooting

Problem 1 – GitHub Cannot Connect to Jenkins

If GitHub reports that it cannot connect, verify:

• Jenkins is running.
• The Jenkins public IP/DNS is correct.
• The webhook URL uses the correct port.
• The EC2 Security Group/firewall allows the required request.
• The URL is not using localhost or a private-only address.

Problem 2 – 404 Not Found

Verify that the webhook URL ends with:

/github-webhook/

Example:

http://54.123.45.67:8080/github-webhook/

Problem 3 – GitHub Delivery Succeeds but Jenkins Does Not Build

Go to:

Jenkins Job → Configure → Build Triggers

Verify:

☑ GitHub hook trigger for GITScm polling

Also verify that the repository URL configured under Jenkins SCM matches the repository sending the webhook.

Problem 4 – Jenkins Starts but Git Checkout Fails

If the webhook triggers Jenkins but checkout fails, the webhook is working. Check:

• Repository URL.
• GitHub username.
• GitHub Personal Access Token for private repository access.
• Token repository permissions.
• Jenkins credential selection.

Problem 5 – Wrong Branch

If Jenkins is configured for:

*/main

make sure you test the lab by pushing to the main branch.

Use GitHub Recent Deliveries for Troubleshooting

GitHub provides webhook delivery details under:

Repository → Settings → Webhooks → Your Webhook → Recent deliveries

For each delivery, you can inspect information such as:

• Event type
• Request headers
• Payload
• Response status
• Response body

You can also redeliver a recent webhook request from GitHub while troubleshooting, which is useful because you do not always need to create a new commit for every test.

Expected Result

After completing the lab, this workflow should happen automatically:

Developer changes code
        |
        v
git add .
        |
        v
git commit
        |
        v
git push origin main
        |
        v
GitHub receives the push
        |
        v
GitHub sends webhook
        |
        v
Jenkins receives /github-webhook/
        |
        v
Jenkins identifies the matching job
        |
        v
Jenkins checks out the code
        |
        v
Jenkins runs the build automatically

Lab Validation Checklist

• ☐ GitHub plugin installed in Jenkins
• ☐ Jenkins job uses the correct GitHub repository
• ☐ Correct branch configured
• ☐ GitHub hook trigger for GITScm polling enabled
• ☐ Poll SCM disabled for this lab
• ☐ GitHub webhook created
• ☐ Payload URL ends in /github-webhook/
• ☐ Content type set to application/json
• ☐ Push event selected
• ☐ Webhook is Active
• ☐ GitHub can reach Jenkins
• ☐ A code push starts Jenkins automatically
• ☐ Jenkins successfully checks out and builds the code

Interview / Review Questions

1. What is a webhook?
2. What is the difference between Poll SCM and a webhook?
3. Why must Jenkins be reachable from GitHub?
4. What Jenkins endpoint receives GitHub webhook events?
5. Which Jenkins build trigger is used for GitHub webhooks?
6. Which GitHub event did we configure in this lab?
7. How can you verify whether GitHub successfully delivered a webhook?
8. If GitHub reports a successful delivery but Jenkins does not start, what would you check?
9. If Jenkins starts but cannot clone a private repository, is that primarily a webhook problem or a Git authentication problem?

Summary

In this lab, we configured an event-driven Continuous Integration trigger between GitHub and Jenkins. GitHub now sends a webhook whenever code is pushed to the configured repository, and Jenkins responds by checking the matching Git repository and starting the configured job automatically.

Final Flow:
Developer → Git Push → GitHub → Webhook → Jenkins → Build/Test/Scan/Deploy

Official References

• Jenkins GitHub Plugin Documentation
• GitHub Docs: Creating Webhooks
• GitHub Docs: Testing and Troubleshooting Webhooks

Updated GitHub + Jenkins webhook lab for current DevOps training workflows.

How to configure Webhooks for Pipeline(Terraform)

 Create a Pipeline in jenkins for your terraform automation

• Go to Jenkins > New Items. Enter terraform-pipeline in name field > Choose Pipeline > Click OK

• Select Configure after creation.
• Go to Build Triggers and enable Trigger builds remotely.
• Enter tf_token as Authentication Token

 

Now Save

Next 

Bitbucket Changes

• Create a new Bitbucket Repo and call it terraform-pipeline
• Go to Repository Settings after creation and select Webhooks
• Click Add Webhooks
• Enter tf_token as the Title
• Copy and paste the url as shown below

              http://JENKINS_URL:8080/job/terraform-pipeline/buildWithParameters?token=tf_token

• Status should be active
• Click on skip certificate verification
• triggers --> repository push

Now Whenever you push changes, to bitbucket , it will trigger the pipeline

How to configure webhooks in Bitbucket to trigger a build in Jenkins? How to trigger automated builds in Jenkins through Bitbucket

 

Jenkins jobs can be triggered many ways. Here are those ways:

1. pull - using poll scm
2. Webhooks (push mechanism) - by triggering a build from Bitbucket or GitHub for every repository changes.
3. through slack channel. We will cover this in a later class. 

Webhooks are triggers that enables developers to trigger Jenkins jobs automatically every time there is a code change

we will see in this article how to trigger a(push) build for every change in bitbucket repository:

Changes needed in Jenkins

1. Install the Bitbucket Plugin:

Go tom Manage Jenkins---Plugin Manager

Search Bitbucket and install without restart

Select the job you would like to configure webhook is for. 

Choose configure 

Click on the build job. 

Go to triggers section and click on Build When a change is Pushed to Bitbucket

Also uncheck poll SCM option(if it was selected earlier)

Changes in Bitbucket

1. go to bitbucket, choose the repository, go to settings, click on web hooks.

2. enter title, url which is your jenkins job url - append b
 example the url should be like this - http://jenkins_public_dns_server_url:8080/bitbucket-hook/

Sample url is given below:

http://jenkins_url:8080/bitbucket-hook/

3. status should be active
4. click on skip certificate verification
5. triggers --> repository push

Now make a code change in bitbucket to see if that triggers a build in Jenkins automatically.