Chinmay Shewale's Blog
How to get started with GitHub REST APIs and Webhooks?

How to get started with GitHub REST APIs and Webhooks?

Chinmay Shewale's photo
Chinmay Shewale
·

5 min read

Table of contents

GitHub is a popular platform for hosting and collaborating on software projects. In addition to providing a web-based interface for managing repositories and issues, GitHub also offers a powerful API for interacting with your repositories programmatically. This API can be used to automate tasks, integrate with other tools, and build custom applications.

One of the most useful features of the GitHub API is its support for Webhooks. Webhooks allow you to receive notifications when certain events occur in your repository, such as when a new issue is opened or a pull request is merged. This can be useful for triggering automated workflows, such as running tests or deploying code.

In this blog post, we'll cover the basics of how to get started with the GitHub REST APIs and Webhooks. We'll walk through the process of setting up a webhook and creating a simple application that responds to events triggered by the webhook. By the end of this post, you should have a good understanding of how to use the GitHub API and Webhooks to automate tasks and build custom applications.

Let's get started by creating an App on GitHub to receive are tokens

You can create an OAuth app from your settings.

Register your application by filling in the details like:

Once an App is created you will receive Client ID and Client Secret. Store it very safely, and treat them as your login ID and password.

For authenticating the user I suggest you to use Postman which enables very easy and feasible API testing. With the help of the Postman Oauth feature you need not store and generate and access tokens and postman also sets the authorization header for you. I will share a basic Postman collection below where you can test some endpoints easily.

Making an API request

You can view all API endpoints over here.

Let's make our first API request from the authorized user using the access token to retrieve the data of the authorized user.

The endpoint we will use is GET https://api.github.com/users

We need to set the Accept Header as : application/vnd.github+json always and set the Authorization header: Bearer <YOUR-TOKEN>

After making the request you will receive a response in JSON format for example:

{
  "login": "octocat",
  "id": 1,
  "node_id": "MDQ6VXNlcjE=",
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "gravatar_id": "",
  "url": "https://api.github.com/users/octocat",
  "html_url": "https://github.com/octocat",
  "followers_url": "https://api.github.com/users/octocat/followers",
  "following_url": "https://api.github.com/users/octocat/following{/other_user}",
  "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
  "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
  "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
  "organizations_url": "https://api.github.com/users/octocat/orgs",
  "repos_url": "https://api.github.com/users/octocat/repos",
  "events_url": "https://api.github.com/users/octocat/events{/privacy}",
  "received_events_url": "https://api.github.com/users/octocat/received_events",
  "type": "User",
  "site_admin": false,
  "name": "monalisa octocat",
  "company": "GitHub",
  "blog": "https://github.com/blog",
  "location": "San Francisco",
  "email": "octocat@github.com",
  "hireable": false,
  "bio": "There once was...",
  "twitter_username": "monatheoctocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z"
}

Now similarly lets create an issue in a repository using the API

Creating an issue in the repository using an API call

This time we'll be using the POST https://api.github.com/repos/:owner/:repo/issues

Here we have to enter some query params in the URL

  • The :owner will be replaced by the username of the repository owner

  • The :repo will be replaced with the repository name

For example, let's consider my test repository rockettest the URL that will be formed will be https://api.github.com/repos/chinma-yyy/rockettest/issues

Now as we want to create an issue we also need to provide some details about the issue, so we will send a body with data like :

{
  "title": "Found a bug",
  "body": "I\'m having a problem with this.",
  "assignees": [
    "octocat"
  ],
  "milestone": 1,
  "labels": [
    "bug"
  ]
}

With a successful request, you can have a new issue created in your repository through an API call. Congratulations, if your issue was created now you just need to read the documentation once and follow along.

Creating a Webhook using REST API

So most of the applications take webhook URLs as input but GitHub has a different approach and I also kinda found out interesting and can be useful in some cases.

Webhooks are basically communicators between two software applications that send a request to a particular address after a particular action is performed. For example, if someone pushes some commits to the GitHub repository, then the server address of the configured webhook will receive a request having all information regarding the push event.

Let's start by configuring one webhook:

We have to make a POST request on https://www.api.github.com/repos/:owner/:repo/hooks where :owner will be the username of the repository owner and :repo will be the repository name.

Now as it is a POST request we need to send a body associated with it, the body must be of the format :

{
  "name": "web", // Should always be name
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "url": "https://example.com/webhook",
    "content_type": "json",
    "insecure_ssl": "0"
  },
}

Here, the name is always set to 'web', and active determines that for every event notification must be sent or not, events is an array of all events the user wants to subscribe to and in the config object we must pass the webhook URL where we will receive all our event requests also the content type you want to receive data in and other security details if required.

If you receive a 201 status code with a response then, Voila you have made it now for every event you subscribed your server will receive a request and you may provide a handler to any specific task as per choice on meeting some conditions. The response after creating a webhook will be something like :

{
  "type": "Repository",
  "id": 12345678,
  "name": "web",
  "active": true,
  "events": [
    "push",
    "pull_request"
  ],
  "config": {
    "content_type": "json",
    "insecure_ssl": "0",
    "url": "https://example.com/webhook"
  },
  "updated_at": "2019-06-03T00:57:16Z",
  "created_at": "2019-06-03T00:57:16Z",
  "url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678",
  "test_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/test",
  "ping_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/pings",
  "deliveries_url": "https://api.github.com/repos/octocat/Hello-World/hooks/12345678/deliveries",
  "last_response": {
    "code": null,
    "status": "unused",
    "message": null
  }
}
GitHubwebhooksAPIsopenaioauth