I’ve written about APIs in a previous post and I’m returning to the topic here, chiefly because they’re so fundamental to much of the work we undertake for our customers, and to the world of software in general. Last time I was discussing rate limiting, but here I’m turning to the topic of web hooks.

Software systems rarely sit in isolation – many things of value that a system can do involve responding to something happening somewhere else, or telling another system that something relevant has happened.

The world of systems integration has an interesting and lengthy history. Data formats, transport mechanisms and protocols combine to describe a means of integration. In the past, you might have dropped a tab-delimited text file into a directory – or depending on the context you might ping a UDP datagram to a gaming server, or post XML to a service bus. But in the current tech landscape for products and apps, the most common language that systems speak is HTTP, the protocol of the web.

Because this is now the easiest language for most developers to work with, the approach has become ubiquitous. Specifically, any product or system worth its salt nowadays has an API, and in most cases if it’s served over the web, it’ll be a HTTP API. Furthermore it’s common practise that the API is not only used by third-parties looking to integrate, but by the product itself (case in point – Amazon’s use of their AWS cloud services).

Poll tax?

The majority of the time, the API of an app is used to instruct the app to do something, or request some information from the app. For instance, an e-commerce product would have an API allowing you to get or update product stock information. But what if you wanted to do something – say, send a text message to a customer – when a new order is placed?

Most APIs out there would have you poll – periodically check in with the API, asking to see the list of new orders. They put the onus on you to find out if something has happened. This is dead easy to implement, but has several disadvantages –

1. Latency. If you check every 5 minutes, there could be a 5 minute gap where you don’t have the data.
2. Server load. Each time you check, you’re asking the API to do some work, even if there’s nothing new to report. This has a real-world cost.
3. Client load. You’re also making a request out to talk to the API. This could have a cost too.
4. Client complexity. You need to write some code to check on a schedule, interpret the results, see if there’s anything new.

Hooking up

All of these disadvantages can be removed – in the world of HTTP – if you have an API which offers web hooks.

With web hooks, you register your own API with the other API: effectively saying, “please give me a call when X happens”. Since HTTP APIs are fairly ubiquitous, your system is likely to have one too – so you just add a new endpoint which is available for the other system to talk to.

That said, this is a trade-off: what happens if the other API can’t contact yours? How would you know if the other API is down? That gives rise to complexities which do need to be considered, but they are well-understood problems which have been solved many times over – and such solutions can be dropped into a system fairly easily.

Web hooks: they’re your friend. If you’re building an API and need to notify the other party – consider using them! You’re doing everyone a huge favour and making systems more effective, responsive and efficient.

Photo by Cameron Kirby on Unsplash