Understanding Webhooks

22 Jul 2023 - rich

How do you use webhooks? How do you create them? How do you troubleshoot them? Fortunately they are very straightforward to setup and use. Still, there may be a few questions that need to be answered.

What Are Webhooks?

Webhooks proide a way for notifications to be delivered to an external web server whenever certain events occur on GitHub.

What Are Webhooks Used For?

Webhooks can be triggered whenever specific events occur on GitHub (push, pull-request, new member added to team, etc…)

A quick note about webhooks

Most of my rants about searching for answers on the web are about people who take an existing piece of documentation, publish another article, pretty much about the same thing, and don’t add much if any additional value or embellishment to the original.

I am not above this myself but would like to think that I am pretty much aware of it when I do and and have a pretty good explanation for adding to all the existing chaff.

When initially setting up webhooks in Github for use with Jenkins, I had a few basic questions that were not really answered…

Questions

1. Where do I need to add my webhook? Why do I need to add it to a repository when I would like any change in any of my repositories to trigger a Jenkins build (but for that specific repository).
2. If I had to add the webhook to my individual repository, why did the name of the webhook remain the same? I mean, it would have made more sense if each repository had its own identifiable webhook.
3. If I had to use the same name, or if I could use the same name, how does Jenkins know what to do with that delivery when it receives it?

Answers

1. you can add webhooks to an organization, a repository or to a GitHub App.
2. (short answer to be expanded later after some additional tests) does not ahve to have the same or consisten name. The webhook is received and parsed by the remote server which extracts information about repostory, event, etc, from the body of the webhook payload.

When you add a webhook, you choose which events you would like to subscribe to. By default, webhooks installed on an organization or a repository level are only subscribed to push events. And, webhooks for GitHub Apps are not subscribed to any events. Check out “webhook events and payloads” for a complete list of webhook events.

How do I create a Webhook

Is it Working? Viewing Webhooks

You can review your webhook deliveries from Github. This includes the HTTP request and the payload as well as the response. Gihub webhooks view provides tooling for testing out your deployed payloads.

For each webhook you create, there exists a “recent deliveries” section within the webhooks information section. You can see, visually, if a delivery was successful or not. Additionally, you can see when the deliveries were attempted. This log persists for 30 days.

Is it Working? Did Jenkins log a Webhook?

references: Cloudbees webhook troubleshooting Testing Webhooks About Webhooks “webhook events and payloads”