APIs vs. Webhooks: What’s the difference?

APIs and webhooks both allow different software systems to sync up and share information. As software applications become increasingly interconnected, it is essential for developers to understand the difference between these two means of sharing data, and select the tool that best meets the needs of the task at hand.

An API is like a portal through which information and functionality can be shared between two software services. The word “interface” is key to understanding an API’s purpose. Just like a web browser is an interface for a human end user to receive, send, and update information on a web server, an API is an interface that provides software programs with the same functionality. 

There are different types and categories of APIs (which we will explore later), but defined broadly, APIs are the most common way for different software systems to connect and share information. Currently, ProgrammableWeb provides a database of over 23,000 APIs that deal with everything from global epidemiological data to dad jokes. Each API is a blank canvas waiting for developers to tie it into other applications and use it in new, creative ways.

A webhook can be thought of as a type of API that is driven by events rather than requests. Instead of one application making a request to another to receive a response, a webhook is a service that allows one program to send data to another as soon as a particular event takes place. Webhooks are sometimes referred to as “reverse APIs,” because communication is initiated by the application sending the data rather than the one receiving it. With web services becoming increasingly interconnected, webhooks are seeing more action as a lightweight solution for enabling real-time notifications and data updates without the need to develop a full-scale API.

Say for instance you want to receive Slack notifications when tweets that mention a certain account and contain a specific hashtag are published. Instead of Slack continuously asking Twitter for new posts meeting these criteria, it makes much more sense for Twitter to send a notification to Slack only when this event takes place. This is the purpose of a webhook––instead of having to repeatedly request the data, the receiving application can sit back and get what it needs without having to send repeated requests to another system.

An important feature of APIs is that they provide two-way communication between different software programs via a request-response cycle, most commonly using the HTTP protocol. In a typical API use case, one software program will ask for a specific set of data from another using an HTTP GET request. Provided the request is valid, the receiving system will respond with the requested data in a machine-readable format, commonly XML or JSON. This is what allows applications to share data regardless of their individual programming languages or internal specifications. The universal nature of API interactions can enable countless scenarios, from an iPhone user checking the local temperature via the AccuWeather API to an Uber driver navigating to their next pickup location via the Google Maps API.

In addition to receiving data, APIs can also handle the full gamut of “CRUD” (Create, Read, Update and Delete) operations between two applications. In other words, APIs aren’t just for displaying data to a user in an interface––they can also be used to make changes to it in the application where it is stored. This is how APIs allow software systems to expand their services and functionality, and integrate with other platforms in a more thorough and meaningful way.

The versatility of APIs makes them powerful tools for developers to extend the capabilities of their applications. Most modern web services include APIs that allow their data and functionality to be incorporated into other tools––in fact, it would be rare to encounter an enterprise web service that does not leverage an API from at least one other application to some extent.

One might think that since webhooks are real-time events that they are technically difficult to implement. Actually, a key advantage of webhooks is that they are easier to set up and less resource-intensive than APIs. Creating an API is a complex process that in some cases can be as challenging as designing and building an application itself, but implementing a webhook simply requires setting up a single POST request on the sending end, establishing a URL on the receiving end to accept the data, then performing some action on the data once it is received.

Common use cases for webhooks include sending new email list subscriptions and unsubscriptions to a CRM system, automatically updating accounting software when invoices are paid, or setting up any type of notifications. In each of these types of events, the information flows in one direction, and no request is necessary to receive updated data.

The same characteristics that make webhooks relatively easy to implement are also the reasons why they are far more limited than APIs. Updating the data a webhook delivers requires reconfiguring it entirely to listen for a different event, and in most cases it would be more efficient to create a new webhook. When two systems share data via an API with multiple endpoints, the receiving system has access to a much broader range of data from the sending system. Also, unlike APIs, webhooks do not allow the sending system to add, update and delete data on the receiving end, which is why webhooks alone are too limited to offer full integration between two applications.

APIs fall under different categories depending on the protocols and architectures that define how they send and receive data. Historically, the most common architectural pattern for API design has been REST, especially for those servicing web-based applications.

REST stands for “Representational State Transfer.” This pattern, defined by Roy Fielding in 2000, allows for two applications to communicate over HTTP in a way similar to browsers and servers. REST is not an official standard––rather, it is a set of suggestions about how to design APIs and other web services. An API is considered “RESTful” if its design abides by the following recommendations: 

• Client-Server: Just like a browser requesting a webpage from a server, in a RESTful API, application A makes a request to a URL hosted on application B over HTTP. Application B then evaluates the request and returns either the requested data or an error message. 
  
• Stateless: The responding system does not need to know anything about the application state of the system making the request to provide an appropriate response. The request alone should contain all the information necessary to deliver the response. 
  
• Cacheability: The response should state whether the receiving system is allowed to cache it or not. 
  
• Layered systems: The API does not rely on a particular system to make the request in order to deliver the response. This means the requesting system could either be a client, a proxy, or any other intermediary.

This simple example follows REST conventions. When you visit the URL, your browser will display a suggested activity to take part in if you are bored in JSON format:

No matter how you make a request to this URL––whether with your browser, with CURL, or an HTTP client library like fetch in JavaScript––the API will return the same object. In addition to REST, other API conventions include SOAP, COBRA and XML-RPC. To date, however, REST the most widely used set of API architecture guidelines.

In 2015, the engineering team at Facebook released GraphQL––a new query language for APIs intended to provide a more flexible alternative to sending requests to endpoints on REST APIs. Without getting too deep into the complexities of GraphQL, the main advantage it offers over traditional REST APIs is its ability to return the exact data needed with each request while avoiding “over fetching” and “under fetching,” problems typically encountered with traditional APIs. 

For example, consider the following situation. A restaurant review app needs to display the titles of the most recent reviews a user has published, along with the last three people to follow that user. Using a REST API, the client would typically have to make three different requests to different endpoints––one to fetch the initial user data, a second to return all the reviews for that user, and a third to return a list of that user’s followers. Using GraphQL, a client could access the same data with a single query the exact requirements:

APIs are the workhorse of mParticle’s technical ecosystem. They are a large part of what enables mParticle to compile an omnichannel view of your customers, and share these profiles with tools across your marketing stack. mParticle’s 280+ direct integrations with leading marketing, analytics, and data warehousing solutions are all powered by richly featured custom APIs that abstract away the complexities of sending real-time data and unified user profiles to downstream systems.

Rather than simple webhook integrations, which are limited to one-way data feeds, mParticle’s partner integrations rest on complete APIs that enable much more robust interaction between the two systems. These APIs are always very active behind the scenes, like when mParticle customers seamlessly direct the flow of their data in the mParticle UI, for example.

In addition to the APIs that power partner integrations, mParticle provides developers at partner companies with various APIs to customize their data collection, and individualize mParticle to their company’s specific needs.

One example is the Profile API, which allows customers to programmatically retrieve user profiles built via mParticle’s cross-channel data collection and identity resolution capabilities. The data retrieved from querying this API can help brands quickly build personalized experiences within or across channels.

Here is a sample request that could be sent to the Profile API to retrieve data on an mParticle user profile:

And here is a sample response to this request:

To explore this API in greater detail, you can experiment with this sample Node application, which calls the mParticle Profile API and returns the result to a native client.

Want to learn more about the direct benefits that CDPs deliver to engineering teams? Check out our Complete Guide to Customer Data Platforms for Engineers.

Hopefully this post has expanded your understanding of these two common methods of sharing data between applications. The same wisdom that applies to all architectures, frameworks, design patters and technologies in software engineering also holds true for APIs and webhooks: everything has its time and place. The key to getting the most out of both tools is knowing which one is right for the job.

1: What is a customer data platform?

2: Developer deep dive: mParticle Sample Apps

3: The engineer's guide to working with marketers