Fotolia
Webhooks explained simply, and how they differ from an API
Webhooks and APIs seem to both accomplish the same goal. So what's the difference? We review what a webhook does, how it differs from an API, and where it is the right design choice.
Years ago, a friend of mine configured his Facebook account so that adding #twit to any of his posts would automatically publish that post on Twitter as well. Since he was constantly promoting his ideas and content on social media, it saved him a fair bit of time. The technology he used to accomplish this is known as a webhook.
In this tip, we'll examine what webhooks are, how they differ from APIs, and what their use in the real world looks like.
Webhooks explained
A webhook is an architectural strategy that configures applications and services to send a web-based message request every time a qualifying event happens. In many ways, you could say it functions as an inverted API.
In the Facebook example, rather than sending a request to the Facebook API to post a message from another platform, or share his news feed, he configured Facebook to actually send a message out to another API in response to his actions. That flips the idea of the API around: The platform isn't asking for anything, but instead relays its own request message. Exactly what message this contains, and where it goes, is completely customizable. All it really needs is a user-supplied web address to send the request to when the action occurs.
To be a true webhook, a web-based message must follow basic web messaging protocols, like an HTTP "POST" request (or HTTPS, if you need some additional security). However, these webhooks can still send messages in a variety of simple formats like SMS and Simple Mail Transfer Protocol (SMTP). Developers can create command lines, set up configuration files or pipe it directly through a user interface to achieve this.
Webhook examples
When it comes to any sort of webhook programming standard, the closest thing is likely If This Then That statements. This is a web application service that will grab any public APIs an application may offer, and then converts them into a message format suitable for a webhook-like process.
Webhooks are an easy way to make your API available for calls, or send text-based responses to users when certain events occur inside the application. Most modern platforms support webhooks, or at least a similar architectural approach, such as Github, Trello, Confluence, Facebook, Stripe and Google Calendar.
Some real-world examples of webhooks include:
- Automatically receive an email every morning about your first meeting in case you forget to check your calendar.
- Have Instagram photos upload automatically to Twitter accounts.
- Configure the doorbell to flash the lights when it rings.
- Receive notification that a payment has been made and processed.
Webhooks vs. APIs
APIs and webhooks both accomplish similar goals, but in different ways.
An API programs something, whether that means it directly creates an order, enrolls an employee or some other type of task. If the developer's goal is to initiate a straightforward, synchronous transaction -- or chain of transactions -- APIs are likely the logical answer. This would also be the case if developers don't want to receive a notification about singular events, but prefer to receive something like a daily workflow report.
On the other hand, a webhook tells an API that an event occurred in order to trigger an action. This is particularly useful in retail scenarios, such as when you need to immediately relay information to users. For example, if a customer wants automatic notifications about changes in order status, the webhook could trigger an API to pull information and notify the user any time it detects a change.
Webhook tools
There are plenty of ways to misconfigure a webhook, such as incorrect data, sending it to the wrong URL and security problems -- such as authentication and authorization. However, there are tools out there, such as RequestBin and Postman, to test webhooks and check, rework and ensure the message was sent properly.
Before you send the message to the final destination, send it to RequestBin and check if it is correct. After that, send the message on to the final destination. If it doesn't work, you can use Postman, cURL or HTTPie to try different messages to make sure it works. Developers can also use these tools to test application performance, at least on a small scale.
RequestBin has a detailed example of using webhooks to post new Github issues to discord. The tutorial includes how to configure the examples through the user interface -- no code required.
