Webhooks vs. APIs: What's the Difference?
Russ Danner is VP Products at CrafterCMS and is responsible for product management, product development and support, and client and partner success. Russ brings over 20 years of software architecture, design, and implementation experience. Prior to CrafterCMS, Russ was Web Experience Management Practice Director at Rivet Logic (now Capgemini) and project lead for the open source CrafterCMS project.
The use of SaaS apps and other software solutions that integrate into an overall tech stack has been rapidly growing. In fact, employees at smaller companies use an average of 26 SaaS apps, and at larger companies an average of 124. The overwhelming number of apps used by employees creates challenges for IT teams in managing a seamless experience.
As companies build sophisticated digital experience applications using a variety of software solutions, they need straightforward ways to share data between them. Webhooks and APIs are the two main ways developers integrate systems and avoid content/data silos, but each has its specific purpose.
Let's look at the different technologies behind the communication of separate systems, and why they're crucial for digital platforms.
What Is an API?
An API, or application programming interface, is a way to request data from another system or software programmatically. In most cases, the requests and responses are in JSON format, but many APIs or web services use XML as well. Most modern APIs are RESTful and follow the methods defined under HTTP to make their use more straightforward for developers. This means APIs can not only request data for third-parties, but can manipulate and delete it as well if authorized. While there are many best-practices companies follow when designing REST APIs, as we'll see later, GraphQL is an even more standardized API for querying data from other systems.
Further Reading: What Is an API Endpoint?
What Is a Webhook?
A webhook is a way to notify other systems that you want an update whenever certain data has changed. Webhooks are predefined instructions, so there's no need for programmers to regularly make requests to external systems for data. Instead, the webhook is set up once and the other system sends data whenever it's triggered.
Many refer to webhooks as reverse APIs because developers need to design an API endpoint for a webhook to call that’s able to parse the data received, which is the opposite of programming requests to an external API. The API endpoint - or URL - is considered a “listener” that waits for the external application to send a request, and transforms the data received however necessary.
When Should You Use Each?
While APIs are everywhere - there's over 22,000 according to ProgrammableWeb - webhooks are much less common. When it comes down to it, APIs are request-based while webhooks are event-based. For this reason, there are specific use cases for both depending on when and how the data is created. Many systems, however, use APIs and webhooks at the same time for different tasks.
If you know data will change frequently, but you don’t need real-time updates, then an API may be the better option. Developers have more control of APIs than they do with webhooks. They can request the specific data they need, whenever they want. They can also take advantage of API pagination features to manipulate the payloads they're receiving and optimize server bandwidth. If the server is seeing high traffic, for example, the request can reduce the paging size and receive a smaller response.
Learn more about APIs: What is an API-First Headless CMS?
APIs are also better if it's critical to know whether the external system is online. With APIs, you're immediately aware if the request was successful because you'll get a response with a status code. Webhooks, on the other hand, only communicate if there's an update, so your software will be unaware if the other system is offline.
Many SaaS applications use APIs if they want to offer full CRUD - create, read, update, and delete - capabilities. That's because webhooks wouldn't be suitable for manipulating data in third-party systems. With APIs, however, developers can deeply integrate with other software and let users modify data across multiple systems from one interface.
For situations where data changes less frequently, a webhook may be the better option. Constantly making API calls and receiving the same response is a waste of bandwidth, so letting the external system notify your software when necessary could be more efficient. Empty responses from API polling is not only inefficient, but it could cause systems to run up against rate limits. Most APIs limit the number of requests over a period of time, or even charge by the request, so frequent polling could be expensive or lead to data limitations. Webhooks avoid this issue by only communicating when there's data to share.
Webhooks are also useful for real-time data. As mentioned, API polling can be extremely inefficient, and getting real-time updates with APIs would require high-frequency polling. APIs don't know when there's no data, so they need to keep checking, but webhooks can continuously send updated data in real-time to your software. The risk with these automatic data transfers, however, is that your software has no control over the flow, and could be overwhelmed with too much data at one time.
Many SaaS applications have webhook functionality for features like emails, profile updates, and other small one-off notifications. Webhooks are better suited for these tasks because users receive notifications in real-time, and don't have to wait for API polling.
CrafterCMS: There's An Even Better Option
GraphQL has quickly become a popular data sharing API solution for many software developers. The query language has many of the benefits of traditional REST APIs and webhooks. The standardized queries give the developer control over the data that the server responds with, which generally leads to smaller payloads and reduced bandwidth. GraphQL also introduces the concept of subscriptions, which lets developers subscribe to certain events - similar to webhook triggers - that requests external systems to send data automatically. These features make GraphQL APIs more suitable for both frequent and infrequent data changes and real-time data situations.
CrafterCMS supports GraphQL out of the box. This means the CMS can efficiently provide content to applications at-scale. Without any backend development, developers can use GraphQL to integrate with external systems and frontend applications quickly. For more on why GraphQL may be the best integration technology of the future, check out Is GraphQL the Next API Standard for CMS?
Magnolia Alternatives: Why Enterprises Choose CrafterCMS
Attention Content Authors: Don't Worry About What Technology Your Headless CMS Developers are Using
Git-Based CMS vs API-First CMS: Is It Either-Or?
Hygraph (aka GraphCMS) Alternatives: Why Enterprises Choose CrafterCMS