As most of what we do on the web can be described by events, webhooks have become a de facto way of connecting systems, whether it’s a new user account creation, successful payment, DockerHub image push event or a new pull request in your Git repository. They are incredibly useful and lightweight way of sharing information.

So, what exactly is a webhook? A webhook is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer. And as most of the providers have strict API rate limits, you will either have to adopt webhooks or accept that your system will always be slightly (or more) out-of-date. The example above shows a typical flow for requesting payments from the users.

Webhooks are sometimes referred to as “Reverse APIs,” as they give you what amounts to an API spec, and you must design an API for the webhook to use. The webhook will make an HTTP request to your app (typically a POST), and you will then be charged with interpreting it. You can think of it as a regular API route that your CLI/UI uses but in this case the user will be 3rd party service that you rely on.

While most developers are consuming webhooks that are produced by popular services such as Stripe or GitHub, sometimes you also want to let users receive webhooks from your application. In this blog post, we will build a simple application where users can register their endpoints and receive events.

Creating a webhook dispatching application

Our application will be written in Go (installation instruction can be found here) but you can choose any language you want and this is just a simple example that demonstrates the outgoing webhook behavior. The code is simple and even non-Go developers should find it readable:

Running your webhook producer

To use our webhook producer we need an endpoint that can receive and help us debug it. For this task, we will be using this free service: https://bin.webhookrelay.com/. Upon opening the link you should be redirected to a unique URL that is your bin. Get the bin address, you will need it in a minute.

Let’s start our application:

$ go run main.go Create webhooks on http://localhost:8090/webhooks

Now, add our bin:

curl --request POST \ --url http://localhost:8090/webhooks \ --header 'content-type: application/json' \ --data '{ "name": "joe", "destination": "https://bin.webhookrelay.com/v1/webhooks/821024d7-12a0-4b41-99f2-71fcc2906989" }'

After adding it, in a few seconds you should start seeing logs:

And in our webhooks bin we should see incoming requests:

Conclusion

To wrap up — webhooks and API requests are similar, both are events and the intent is to share information between systems. While API polling might look like a nice solution early on, having too many users relying on it could bring your backend down or considerably affect performance.

To successfully implement webhooks in your system, consider:

User should be able to specify a destination of the webhook

While most systems only allow a single destination to be added for webhooks, you might want to allow more.

Retry webhooks if the status code is >=500. While some might argue that we should retry with 4XX status codes, they usually mean that it’s a bad request and we shouldn’t retry the same request.

Interested or working with webhooks? Check out how you can receive webhook on localhost or private networks in our examples collection. Webhook Relay has a free tier for developers!

Originally published at webhookrelay.com on July 13, 2018.