Examining use cases for asynchronous APIs: webhooks and WebSockets

Ian Douglas

October 25, 2023

In an age where digital immediacy and real-time feedback dominate user expectations, asynchronous APIs stand out as a beacon for enhanced interactivity and efficiency. These APIs embrace the webhooks and WebSockets model, enabling event-driven architectures that power many of today’s leading tech platforms. Let’s explore the top five technical merits of asynchronous APIs with examples of companies that have effectively integrated them.

What are webhooks and WebSockets?

Let’s start by examining the difference between webhooks and WebSockets.

Webhooks are stateless, meaning that each event notification is independent and carries all the necessary information about the event. Webhooks act a lot like RESTful API calls because HTTP is a stateless protocol and each connection needs to provide its own context for the action needed on a given resource. Webhooks are generally called on an as-needed basis when an event occurs, as opposed to a long-lasting connection like WebSockets.

WebSockets, on the other hand, are stateful, meaning that the client and server maintain a persistent connection and can share state information throughout the lifetime of the connection. This long-lasting connection allows the client and server to remember the “state” of the conversation. However, if a WebSocket connection is interrupted and reestablished, the client and server need enough context in that connection to resume their conversation.

Real-time interactivity and engagement

One of the foremost advantages of asynchronous APIs, especially WebSockets, is the ability to offer real-time interactivity. Unlike traditional request-response models, WebSockets establish a two-way communication channel, enabling servers to push data to the client instantaneously. Slack, the collaboration platform, utilizes WebSockets to instantly deliver messages and notifications, ensuring a seamless conversational experience. The end result is a highly engaged user base, with data being exchanged in real time.

Slack also allows users to use third-party webhooks to carry their event-driven architecture to another level. Users can generate content within Slack based on external events, or vice versa, to trigger external webhooks when a message is created within Slack.

Efficient use of resources

Webhooks, an integral component of asynchronous APIs, play a pivotal role in optimizing resource usage. Instead of periodically (and constantly) polling servers for data or checking if a task is complete, systems can rely on webhooks to notify them when specific events occur. GitHub, the popular software development platform, leverages webhooks for various operations, such as alerting Continuous Integration (CI) tools when a new commit is made. This eliminates unnecessary network requests, reducing server load and ensuring optimal performance.

That said, WebSockets still send a “keep alive” packet about every 30 seconds to maintain the connection between the client and server, but this approach is still far more efficient than the polling methods of typical RESTful APIs.

Enhanced scalability

An inherent benefit of event-driven architectures powered by asynchronous APIs is their ability to scale effortlessly. Stripe, the payments infrastructure giant, employs webhooks to notify users about different events, like charge completions or invoice updates. By decoupling the event generation from its consumption, Stripe ensures its systems remain resilient and able to scale based on demand without degrading performance.

Scalability is an interesting aspect of API performance. An early limitation of WebSockets was the number of simultaneous clients that a server could handle, but some clever networking tricks with load balancers and virtual networks now allow for millions of connections.

Improved user experience

With the rise of web applications that demand instantaneous feedback, asynchronous APIs deliver an unmatched user experience. Trello, the visual collaboration tool, uses WebSockets to update boards and cards in real time. When a team member makes a change, every other member views the update instantly, which supports collaboration and helps keep everyone on the same page.

Many organizations can keep clients up to date in this fashion using a “publish/subscribe pattern,” also commonly referred to as “pubsub”. When an event happens, like a team member updating a card in Trello, that event is “published” to a channel that other teammates subscribe to when loading the UI. The WebSocket connection “subscribes” to these event channels and the teammate’s client can act on that new event.

Flexibility in integrations

An often-underestimated merit of asynchronous APIs is the flexibility they offer in third-party integrations. Platforms like Zapier, an automation tool, thrive on webhooks to connect disparate systems. Users can set triggers in one application to initiate actions in another, weaving a web of interconnected tools that work synchronously. This flexibility expedites workflows and automates manual tasks, driving efficiency.

Similar to the “pubsub” model described above, tools like Zapier can also publish these events to a similar channel, allowing for multiple parallel events to be triggered simultaneously.

Caveats: when asynchronous may not be ideal

Asynchronous APIs have a lot of advantages over RESTful APIs, although the RESTful architecture can mimic many of the features mentioned above. However, despite these new features, it’s important to recognize where asynchronous architectures might not be the best fit.

• Data consistency: Data consistency is paramount in many applications—especially financial systems like banking platforms. Asynchronous systems can sometimes lead to temporary data inconsistencies, which can be detrimental in such contexts. It’s therefore important to use highly-detailed timestamping in order to know which information is to be processed in the correct order.
• Complex error handling: Handling errors in asynchronous setups can be more complex than synchronous counterparts. The “unknown” nature of when events are generated and when they are handled means that errors might need sophisticated recovery mechanisms to replay what happened. Reproducing bugs becomes more complicated as a result.
• Overhead of infrastructure: Asynchronous architectures, especially when driven by webhooks, may require a robust infrastructure to manage event subscriptions and deliveries. For small applications or startups, this overhead might be overkill and unnecessary.

Wrapping up

The choice to implement asynchronous APIs, be it through webhooks or WebSockets, stems from the desire to craft scalable, efficient, and interactive applications. Platforms like Slack, PayPal, and Stripe exemplify the strength of this architecture. However, the suitability of this approach hinges on the specific requirements and constraints of the application. Like all architectural decisions, a careful analysis of the needs and trade-offs is essential. But when aligned with the right use case, asynchronous APIs emerge as a modern marvel of digital engineering.

We have some great documentation to help you get started with WebSockets. If you’re looking to build a callback architecture for your event-driven work, we have you covered with webhooks, as well.

Technical review by Pooja Mistry and Melinda Gutermuth.