Choosing Between Webhooks and REST APIs

Webhooks and Representational State Transfer (REST) APIs each offer lightweight methods of communication between two endpoints. When choosing between Webhooks or REST APIs for developing a feature, first consider what these two technologies offer. Consider too their similarities, differences, strengths, and weaknesses.

The Value of Webhooks

Webhooks communicate between two endpoints when triggered by new or changed data becoming available at one of the endpoints. With webhooks, communication occurs in one direction — from source endpoint to destination endpoint (such as server to client or service to service).

Webhooks provide event-driven communication in real time. They send data through HTTP POST requests from the source endpoint to the URL provided by the destination endpoint.

Webhooks are resource efficient because the destination endpoint never requests data from the source endpoint. Instead, the source endpoint automatically sends data only when it becomes available. In contrast, APIs consume resources to poll the source endpoint until the requested data is available.

Example Use Case for Webhooks

You can configure a webhook to trigger when a branch protection rule is changed in a GitHub repository, sending immediate notification of the change to an external service like Slack or Discord. The webhook will send the notification without delay or batching.

The Value of REST APIs

REST APIs enable communication between two endpoints in either direction. REST APIs mediate the call and response between the requesting endpoint and the responding endpoint (regardless of which is client or server). Data can be viewed, modified, created, or deleted between endpoints.

Rather than a strict protocol, REST APIs are based on a set of guidelines for building APIs:

  • client-server separation
  • uniform interface for resource identification, manipulation, and representation between endpoints
  • statelessness
  • cacheable resources
  • layered system architecture
  • optional code-on-demand

REST APIs send data between endpoints through the HTTP methods GET, PUT, PATCH, POST, and DELETE.

Client-server communication is stateless: requests are separate from each other, information is never stored between requests, and each component layer can only access the resources it interacts with. However, frequently requested resources can be cached to reuse for identical requests.

Optionally, the client can request, download, and run code from the server.

REST APIs are lightweight and flexible. The REST guidelines allow for lean APIs, implementing only what is needed for the task at hand. This consumes fewer resources in processing requests than other fully featured APIs with strict requirements. REST APIs also offer flexibility in response format, such as HTML, JSON, Python, PHP, and XML. Other APIs are restricted to specific formats, such as XML for Simple Object Access Protocol (SOAP).

Example Use Case for REST APIs

You can interact with resources in GitHub repositories through the GitHub REST API using GitHub CLI, curl, or JavaScript. Interactions include specific requests for data with the HTTP methods GET, PUT, PATCH, POST, and DELETE. These provide on-demand access to repository resources. With scripting, you can then automate repetitive tasks or processes involving the transfer and modification of data, such as release management and CI/CD pipelines.

Comparing Webhooks and REST APIs

Webhooks and REST APIs both facilitate communication between two endpoints using HTTP methods. But these technologies have distinct features and capabilities best suited to different situations.

When to Choose Webhooks

Webhooks are a good choice when you require immediate communication from one endpoint to another as soon as new information becomes available at the source endpoint. Webhooks are ideal for pushing notifications in real time with minimal latency.

Webhooks can also meet your needs when you require resource efficient and inexpensive communication in a single direction. Because webhooks only trigger at the source endpoint, the destination endpoint never sends repeated requests for information before it is available. By avoiding polling in this way, webhooks free up the resources required by APIs for processing unnecessary requests.

When to Avoid Webhooks

Some applications lack support for webhooks. If you are working with such an application, ignore webhooks and consider leveraging an API for your purposes.

Webhooks are limited to the HTTP POST method sent from source to destination. This occurs only when triggered. Avoid webhooks if you require:

  • data that can be viewed, modified, created, or deleted
  • ongoing communication back and forth between two endpoints

Webhooks offer real-time communication without queuing or batching. However, if the source endpoint experiences downtime, the destination endpoint might miss receiving data that never triggered the webhook. Avoid webhooks if the source endpoint’s uptime is unreliable.

When to Choose REST APIs

REST APIs are a good choice when you need complex interactions or tasks to be carried out between two endpoints. REST APIs facilitate:

  • ongoing communication back and forth between client and server
  • viewing, modifying, creating, and deleting data through HTTP GET, PUT, PATCH, POST, and DELETE methods
  • transferring data in a variety of formats, including HTML, JSON, and XML
  • serving code-on-demand

REST APIs also offer advantages from an infrastructure perspective. REST APIs are:

  • compatible with most applications
  • lightweight in comparison to APIs with stricter requirements than REST constraints
  • modular layered systems, which support scalability, maintainability, and security

When to Avoid REST APIs

REST APIs only offer on-demand server responses. Polling compares repeated responses to identify when the requested information becomes available. High polling rates can increase the resources required by unnecessary API calls, response processing, and error handling. At the same time, polling rate limits can affect the timeliness and accuracy of responses. Avoid REST APIs if you require low-latency, real-time communication between endpoints.

REST APIs demand time and effort from developers to build and maintain connections to endpoints. Each REST API has unique requirements, and these may evolve over time across versions. Avoid REST APIs if you are unable to learn, build, monitor, and maintain endpoint connections.