What Are Webhooks & Services in GitHub? Explained in Simple Terms

So far, we've covered all of GitHub's definition and core features, and how to create a GitHub account. But any large group or project will have customizations or additional services they'd like to incorporate.

Fortunately for us, GitHub can be used in a variety of ways. We'll go through how to use the GitHub hooks system and API to make GitHub work the way we want it to in this part.

The easiest approach to have GitHub interface with external systems is through the Hooks and Services area of the GitHub repository administration.

Services

First, let's have a look at the Services section. Both the Hooks and Services integrations are located in your repository's Settings section, where we previously looked at adding Collaborators and modifying your project's default branch. 

You'll find a section called Services and Hooks setup under the "Webhooks and Services" tab

You can choose from dozens of services, the majority of which are integrations with other commercial and open-source systems. The majority of them are for CI services, bug and issue trackers, chat room systems, and documentation systems. 

We'll go over how to build up a very basic one, the Email hook. You'll get a configuration screen similar to the Email service setting if you select "email" from the "Add Service" selection.

If we click the "Add service" button in this example, the email address we specified will receive an email whenever someone pushes to the repository. Although services can listen for a variety of events, most just listen for push events and then act on the information.

Whether you have a system in mind that you'd like to combine with GitHub, look here to see if there is already a service integration available. You can utilise Jenkins' built-in service integration to initiate a trial run whenever anyone pushes to your repository, for example, if you're using Jenkins to perform tests on your codebase.

Webhooks

If you require anything more particular or want to interact with a service or website that isn't on this list, you can utilise the more generic hooks system instead. Hooks for GitHub repositories are quite straightforward. You provide a URL, and GitHub will send an HTTP payload to it on any event you specify.

In general, you can put up a simple web service to wait for a GitHub hook payload and then do something with it whenever it arrives.

In the Webhooks & Services setup section, click "Add webhook" to activate a hook. This will take you to a Web hook configuration page.

A web hook's configuration is straightforward. In most cases, all you have to do is type in a URL and a secret key and click "Add webhook." You have a few options for which events The default is for GitHub to only send you a message for the push action, as and whenever anyone submits code to almost any version of your repository.

Let's look at a simple web service that may be used to handle a webhook. We'll use the Ruby web framework Sinatra because it's simple and you'll be able to see everything we're doing.

Let's imagine we want to be notified when someone commits to a specific branch of our project.

With code like this, we could do it very easily:

require 'sinatra'

require 'json'

require 'mail'

post '/payload' do

  push = JSON.parse(request.body.read) # parse the JSON

  # gather the data we're looking for

  pusher = push["pusher"]["name"]

  branch = push["ref"]

  # get a list of all the files touched

  files = push["commits"].map do |commit|

    commit['added'] + commit['modified'] + commit['removed']

  end

  files = files.flatten.uniq

  # check for our criteria

  if pusher == 'schacon' &&

     branch == 'ref/heads/special-branch' &&

     files.include?('special-file.txt')

    Mail.deliver do

      from     'tchacon@example.com'

      to       'tchacon@example.com'

      subject  'Scott Changed the File'

      body     "ALARM"

    end

  end

end

Using the JSON payload that GitHub sends us, we're inspecting who submitted it, which version they sent it to, and also what files got modified in all the commits that were pushed. Then we evaluate it to our parameters and send an email if it matches.

You have a beautiful developer console on the same page where you put up the link up to develop and test something like this. You may observe the most recent attempts by GitHub to provide that webhook. You may examine when a hook was dispatched, if it was effective, and the body and headers for each hook's request and response. This simplifies testing and debugging.