2.2 How GitHub Webhooks Work

In order to make this type of application work, we're going to use a feature called webhooks, this is essentially an event when ever something takes place within our repository, GitHub is going to notify our application. And it does so with this webhook. Now, other services have things like webhooks. They might not be called webhooks, but it's essentially the same thing. So the first thing we're going to do is create our repository. So, on GitHub's page just click on the new repository button, and it doesn't matter what you call this, but I'm going to call it, get powered. This is going to be a public repository because I don't have any private repositories with GitHub and you could include a README if you wanted to. I'm going to leave that. And just click on Create repository. Now, you will want to go to Settings, and then there is an option for webhooks and services, and if you click on the Add webhook button, then we can add a webhook. Notice what the first field is. This is the payload URL. Whenever an event takes place, in this case, it's going to be for the push event. Which we can see right here. GitHub is going to send a request to whatever URL that we specify. Now this is the problematic thing about developing this type of application. In order for our application to receive these requests, GitHub has to be able to access our application. Most of the time we are developing our applications either locally or within an internal network. It's usually not something that an external resource like GitHub could access. Now, we could change that we could open up the ports on our firewall and things would work like that. The alternative is to just emulate what GitHub is going to send us, and that is why we are going to use a tool like Fiddler. In the code download, I have two files. One of those is a JSON payload from GitHub, something that we can use in order to develop our application. Now we won’t be able to test everything by emulating a request, but it’s going to go a long way towards getting us to that end goal of having a working application. So we won't be able to actually set up the webhook yet. This is something that we will do after we have something that is living on the web that GitHub can access. So instead of setting up the webhook we're going to go to the developer documentation, conveniently, there is a link here. So let's just go there, and this will give us some information about webhooks. It won't give us everything that we need, but it at least gives us a good amount of information. Now first of all, you can see that there are many events that we can listen for, or at least that we can have GitHub send to our webhook. But really, all that we want is a push. Because when somebody pushes to our repository that means that something has changed, and that's really the only time that we want to go out, find what has changed, and then modify the files that we have on our application. So let's click on push and we will see some of the information. Now the payload that GitHub is going to send us is a JSON structure. And what we see here are all properties on that JSON structure. So it's going to have ref, head, before, size. And really, a lot of this information is not really going to help us with our application. However, this commits is, this is going to be an array of all the commits that were part of the given push. Now if we scroll down, we will have an example of the payload from a push request. And you can see that there is this commits, it is an array, and for every commit that was part of a push, there's going to be information about that commit. All the way down to what was added, what was removed, and what was modified. Now here there's just one file that was modified. And unfortunately, this just shows one commit within this push. So if we look at the file that I have included with the code download, it will give us a little bit more of an example because there are two commits with this push. They are going to be in the order that they were committed, so the earliest is going to be first and of the last commit will of course be the last. But it does have the author information, who committed that information, and then once again we have added, removed, and modified. And these are just arrays that have string values of the files that were either added, removed, or modified. Really that's all that we need, because that is going to tell us what files that we need to either add, modify, or delete from our local store, and we would be good to go. So that's one commit. If we scroll on down a little bit more, then we have another commit where two files were modified as opposed to one. So this is the final format that we are going to be working with. And once again, while there is a lot of useful information here, really the only things that we want are within the commits array. So the logic is going to be pretty simple. We are going to, of course, first of all, parse this JSON into an object that we can read. Then we are going to iterate over all of the commits. And we are going to find what we need to add, remove, or modify within our local store. Now we could use GitHub's API, if we wanted to, but that's going to also complicate some things because we have to go through authentication and all that stuff. Instead, if we just rely upon the payload that GitHub is going to send our webhook, we can easily get the raw files. And it's really nothing more complicated than that. So now that you know how we are going to approach this application, the implementation is rather straightforward. In the next lesson we're going to create our project. And we are going to create a controller for accepting these requests.