7 Jul 17, 2018

What is a webhook?

The Webhook is the Web's way to integrate completely different systems in semi-real time.

As time has passed, the Web (or more precisely, HTTP, the protocol used for requesting and fetching the Web site you're currently reading) has become the default delivery mechanism for almost anything that's transferred over the Internet.

Refrigerators, industrial control systems, lightbulbs, speakers, routers, anti-virus programs – everything is controlled via the Web these days. It's not because HTTP is perfect, fast or fault tolerant, rather, it's because everybody speaks it. It's very easy to send and request a HTTP call. In fact, many programming languages can do it in a single line of code.

With an URL, you can send and receive information to and from any other system, often in the form of an API – Application Programming Interface, a defined set of URLs that can act on a system.

But what if a regular API isn't enough, what if I don't want to ping for data from the API every minute – what if they could just let me know if something changed? As that became a growing need, the word for applications exchanging information automatically like this came to be known as a Webhook. Something happened? Nudge my webhook and I'll know!

A general method of setting them up also started taking form: subscriptions. On most systems, this involves setting these subscriptions up by – you guessed it – a personal fax to the system operator, who can then set it up for you!

Sorry, just kidding. Webhooks are of course also set up via the Web, and many sites provides either a visual user interface for setting them up, or via an API: that way, other applications can subscribe and unsubscribe to your application as they please.

Implementation types

While Webhooks aren't a standard, most people implement them in the same way: When an event happens in your program that another program is subscribed to, loop though each subscription and check whether it actually has access to view that thing, and if so, send a HTTP request to your subscriber's URL.

The content of the request can then be either the actual content (mostly in JSON or XML format), or a reference to the content that can be fetched later: something happened, but call this other URL to see exactly what happened. Doing it like that can save on bandwidth if you batch requests later (fetch the latest since last time).

Obviously, and the whole reason we're doing this: it is then up to the subscriber to carry out an action on the Webhook if it is needed.

A diagram depicting a common way to handle webhook subscriptions in a scalable, event-based manner

A diagram depicting a common way to handle webhook subscriptions in a scalable, event-based manner

Did my toaster send a Webhook about my toast finishing? Better send a text via Trello to remind me there's breakfast! (I have a bad short term memory)

But what happens if problems occur along the way?

Error Handling

If you don't take certain precautions, Webhooks are very prone to failure and lost data.

If I'm suddenly unable to send webhooks to my subscriber, it might be a good idea to re-send it later at some point. But how long should I wait? If I send it a second after, it's probably still down. Maybe 10 seconds or 10 minutes are better for a specific use case. Maybe they'll be completely bombarded by my retries and they'll be worse off. Maybe random retry times, or constantly rising ones would solve the problem.

You might also not want to keep sending a Webhook an infinite amount of times. That is a long time, after all.

Speaking of time: it might be work it to consider timeouts for your use-case. Even though you're great at implementing fast software, maybe your customers aren't, so set a timeout that's reasonable for all parties, or you'll risk delivering duplicate Webhooks to your customers when retrying due to timeouts, or maybe they'll never get their data.

Maybe you want to give control to your subscribers: let them view a log of the failed requests, and let them re-send specific requests at their leisure.

All of this requires a way to queue your calls: don't do them while delivering another request, for example.

Webhooks should always be queued.

That includes the recipient side. You can't be sure that those you're subscribing to will wait forever to hand over the requests; you need to answer webhooks quickly, a couple seconds should be more than plenty to queue your action and return a response. So queue your actions, too!

As they say: your webhook should do almost nothing.

Testing your Webhook

What if you want to get to started with Webhooks, but don't have a system set up to receive them? What if you're developing a Webhook-based system, and you just want to see whether it works?

For that use case, I made Webhook Tester for fun back in March 2016 – I often needed to test webhooks, so I decided to build my own site that worked like I wanted, and it's become really popular, now on page 1 on Google if you search for webhook.

What can I use Webhooks for?

Almost every cloud service has some sort of Webhook functionality, but if you're not a developer, they're hard to use. For that, check out IFTTT (if this, then that), or Zapier – under the hood, they use Webhooks.

What do you use Webhooks for? Let me know in the comments!

7 Responses to “What is a webhook?”

  1. Vignesh

    Useful. thanks

  2. TL

    Thank you for this article. Also, I’m a fan of your webhook tester.

  3. David Multer

    All kinds of developer integrations like Stripe, Drip, GitHub, etc. Also looking for ways to help other developers do a great job integrating webhooks.

  4. Edward Yang

    Thank you for sharing, I’m very interested in Jira webhook test with your tool.

  5. Eric

    I understand that webhooks are very useful when included in a webapp.
    If we want to receive data from a remote site to record in our DB, do you think is it the best way to receive the data ?

  6. Simon Fredsted

    Hi Eric, depending on your requirements regarding latency, performance, etc., webhooks might be able to solve your issue. You could also look into DB replication across WAN.

  7. Gerard ONeill

    I was trying to implement a webhook for Hubspot, and I thought to contact another site (our own), I’d have to implement CORS. So I hooked up your URL (Awesome) as the target.. and found that the “simple” CORS call included all of the data.. Since I didn’t need a response, I don’t have to change anything! I love those AHA moments.

Leave a Comment

Note: Your comment will be shown after it has been approved.