New to webhooks? Start here.

As web developers who make serious efforts in keeping up with new technologies, we are hit with “new and shiny” tools and concepts almost always, and it’s not slowing down. Outside of the not-sure-what-to-adopt JavaScript world, I feel the Webhook® is here to stay.

There’s all this communication happening via APIs these days. You look up what the API is offering and you consume it. Think of webhooks as the siblings of API calls. It’s you saying you want to be notified when something changes instead of polling for those changes like you might do with an API.

Sometimes you tell a server what you want and sometimes it tells you what it’s doing. That’s a webhook.

Let’s look at the differences between an API request and a webhook request.

API Request

Let’s say you make a request to an API for a list of Users in JSON format. Typically, the server will check if you have the proper credentials, and if you do, then gives you the Users you requested.

Webhook

Let’s say you make an update to a User record in the administration area of your app. You click “Save” and get a success message. Cool. But what if another server wants to know about that change? A webhook could be fired off, typically immediately, telling anyone who is listening that the User was just updated.

A webhook broadcasts an action was taken on a server.

So how do I use one?

Good question. From here on, we’re going to focus on the consumer side of things. I’m going to guess there is at least one tutorial out there about creating webhooks using your specific tool or framework so I’ll leave that research up to you.

Let’s walk through the concept at a high level:

  • A URL is created on your server that is ready to accept and process a POST request. The POST request could come in as JSON, XML, form-data, etc.
  • You provide the URL to a service (the webhook provider) that will be sending the POST request
  • An action is taken with that service (maybe a record gets created)
  • The service then makes a POST request to any URLs it was given to notify of that specific change
  • Your server would then process that request and send a POST request back to the webhook provider, letting them know you received the payload successfully (or not)

In the real world.

I hope you see how webhooks could be leveraged to do some really, really cool things. Just look at what GitHub’s webhooks have done for deployment automation.

Speaking of GitHub, I’m going to assume a good portion of you have a GitHub account. We’re going to use GitHub as a real world example so you can follow along at home. If you don’t have a GitHub account, no worries… that’s what the pictures are for.

Instead of going through all of the little details about how to create a listener URL on a server, we’re going to use Webhook Tester. All it does is create a URL that listens for any incoming POST requests. It’s even real-time!

Cool. Now simply click the green “Copy” button in the top right corner. We’re ready to give this to a webhook provider to see what they give us.

We’re going to use GitHub’s webhooks. More specifically, we want Webhook Tester to be notified when we make a comment on a commit within a certain repository.

*You’re going to need at least one repository with at least one commit.

Go into the “Settings” for a repository and find the “Webhooks” link on the left. I don’t have any webhooks yet, so let’s click on “Add webhook” in the top right.

Here’s where it gets good. Let’s paste our URL we got from Webhook Tester in to the URL field for the webhook. Let’s also set our response type to JSON, and narrow our notifications to “Commit comments”.

After hitting “Add webhook”, GitHub is kind enough to go ahead and send us a test request to ensure our server (Webhook Tester) is receiving its POST requests. That’s all great, but we want to see it do what we told it! Let’s go make a comment on a commit via the web interface.

Added some Markdown formatting to see what comes through in the payload.

Now, back to Webhook

There it is!

There are our two POST requests sent from GitHub. Be sure to look through the JSON payload. GitHub does a great job of giving us back any and all information we could possibly need for the commit comment.

I hope this has demystified the webhook concept and you start thinking about how you can leverage this concept in your next project.