Webhook vs API: Key Differences and Use Cases

APIs and webhooks are two common ways apps communicate with each other.

Before we get into what they are, how they differ, and how they’re used, here’s a simple way to understand them:

Imagine you want to grab coffee with your extremely busy friend.

1. An API is like repeatedly texting your friend to see when they’re available for coffee. They may say they are unavailable but you keep checking just in case. 📱 — You initiate the interaction.

2. A webhook is like your friend texting you when they’re actually free to grab coffee. You don’t have to keep checking. They will let you know when they are free. All you have to do is give them your number (so they know what to use to call you back) 👋 — Your friend decides when to notify you.

What Is An API: How They Work and How To Set Them Up 🌉

API stands for Application Programming Interface. It is a set of rules and convention that enable applications, systems, and devices to connect and exchange data.

Common API Styles and Protocols

Here are a few common API approaches you have likely heard about:

REST (REpresentational State Transfer)

• This is the most popular API architectural style.
• Uses HTTP methods like GET, POST, PUT, and DELETE.
• Follows a stateless architecture, meaning each request is independent and carries all the necessary information.

SOAP (Simple Object Access Protocol)

• A protocol designed for exchanging structured information.
• Uses XML for requests and responses.
• Known for its strong security features and reliability in enterprise systems.

GraphQL (Graph query language)

• Developed by Facebook for flexible data fetching.
• Allows clients to request only the data they need, reducing over-fetching.
• Uses a single endpoint for all queries and mutations.

gRPC (Remote Procedure Call)

• Developed by Google for high-performance communication.
• Uses HTTP/2 for faster data transmission.
• Ideal for real-time applications and microservices.

WebSocket

• A communication protocol that allows data to flow back and forth between the client and server at the same time.
• Commonly used for live updates like chat apps or real-time notifications.

How APIs Generally Work

It’s important to note that APIs are a two-way communication. What this means is that you have two parties, one making a request and another one receiving that request, and subsequently choosing what to do with the request before sending back a response.

These two parties are the API client and the API server.

API Client

The API client starts the exchange by sending the request to the API server. For example, a user may start a request by entering a search term, like looking up a book title to see more information about it.

API Server

The API server is responsible for handling authentication, validating inputs, and getting and manipulating data.

API Client                API Server
    |                          |
    | 1. Send request          |
    |    (e.g., search term)   |
    |------------------------->|
    |                          |
    |                          | 2. Request is processed 
    |                          |
    |                          | 3. Server processes data
    |<-------------------------|
    | 4. Response is sent      |
    |    - Status code         |
    |       (e.g., 200 OK)     |
    |    - Headers             |
    |       (e.g.,Content-Type)|
    |    - Body                |
    |       (e.g., data)       |
    |                          |

There are two other components at play here, the API request and the API response.
The API request is the request the API client makes.
The API response is what the API server sends back.

API Request

An API request usually includes:

• Endpoint: The URL that targets a specific resource (e.g., /books).
• Method: Defines the action (e.g., GET, POST, PUT, DELETE).
• Parameters: Extra details passed to customize the request (e.g., a “topic” filter).
• Headers: Key-value pairs that provide extra info (e.g., content type or authentication).
• Body: Contains data for creating, updating, or deleting a resource (e.g., book content).

API Response

An API response usually includes:

• Status Code: A three-digit code that shows the result (e.g., 200 OK, 201 Created, 404 Not Found).
• Headers: Key-value pairs with extra details about the response.
• Body: The actual data or an error message if something went wrong.

APIs in the Real World

Let’s cement this information by seeing how different apps allow you to use their APIs.

📋 How Trello Uses APIs

Trello offers an API that allows developers to interact with Trello boards, cards, and lists programmatically.

• With the Trello API, you can create, update, and delete cards, boards, and lists.
• Unlike webhooks (which only let your app receive data), APIs let your app both send and receive information from Trello.
• This is useful for automating task creation, syncing data with other tools, or building custom Trello features.

An example of how you can create a new card called New Feature Request in a specific list, by using the Trello API:

fetch("https://api.trello.com/1/cards", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "New Feature Request",
    desc: "User requested a dark mode feature.",
    idList: "60d5b2cd8a1234567890abcd",  // The ID of the Trello list where the card should be added
    key: "YOUR_API_KEY",
    token: "YOUR_API_TOKEN"
  })
});

1. This request tells Trello, “Create a new card called ‘New Feature Request’ in the specified list.”
2. The Trello API processes the request and adds the card.
3. The key and token authenticate your request, ensuring only authorized apps can make changes.

🌐 How Slack Uses APIs

Slack offers a powerful API that developers can use to build custom integrations, automate tasks, and interact with Slack data.

• With the Slack API, you can send messages, retrieve channel history, manage users, and more.
• Unlike webhooks (which only let your app receive data), APIs let your app both send and receive information from Slack.
• This is useful for building chatbots, scheduling messages, or fetching data from Slack for reports.

An example of how you can send a new message on Slack by using the Slack API instead of going on the app and typing it out in their UI.

fetch("https://slack.com/api/chat.postMessage", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer xoxb-1234567890-0987654321-abcdef"
  },
  body: JSON.stringify({
    channel: "#general",
    text: "Hello, team! 👋",
    username: "BotBuddy"
  })
});

1. This request tells Slack, “Post a message saying ‘Hello, team! 👋’ in the #general channel.”
2. Slack’s API processes the request and posts the message.
3. The Authorization header includes your Slack token, which authenticates the request.

What Is A Webhook: How They Work and How To Set Them Up 📩

A webhook is an event-driven communication between apps. This means that the webhook sends data to another app when a specific event happens.

For example, imagine you’re using a payment app. When a customer makes a payment, the app can automatically send a webhook to your server with details about the payment, like the amount and the customer’s name. Your server doesn’t have to keep asking the payment app for updates. It just gets notified when something important happens.

How Webhooks Generally Work

Creating a webhook involves setting up a system where one application automatically sends data to another when a specific event happens. Here is a simple step-by-step overview:

Choose the Event to Trigger the Webhook

• Decide what event should trigger the webhook.
• Example: A new user signs up, a payment is made, or an issue is created in a project management tool like GitHub.

Set Up the Webhook Endpoint (Receiver)

• Create a URL (an API endpoint) in the destination system to receive the webhook request.
• This is usually a REST API that listens for incoming data.
• Example: A server with a destination URL like https://yourapp.com/webhook.

Configure the Webhook in the Source System

• In the source system (where the event happens), configure the webhook by providing:
  • The destination URL (your webhook endpoint).
  • The type of event it should listen for.
  • Authentication details, if needed.

Send Data When the Event Occurs

• When the event happens, the source systems sends an HTTP request (usually a POST request) to the destination URL and includes relevant data in the JSON format.
• Example payload:

{
    "event": "user_signed_up",
    "user": {
        "id": 123,
        "name": "John Smith",
        "email": "john.smith@example.com"
    }
}

Process the Webhook in the Destination System

• The destination system receives the webhook request.
• It validates the request, extracts the data, and processes it (e.g., storing it in a database or triggering another action).
• It usually sends back a 200 OK response to confirm it received the webhook.

Handles Errors and Retries

• If the webhook fails (e.g., the destination server is down), the source system may retry sending the request after some time.

   Event Source                   Destination Server
      |                                 |
      | 1. Event occurs (e.g., new user signup)
      |                                 |
      | 2. Webhook automatically ------>|
      |    sends data                   |
      |                                 |

Webhooks in the Real World

Let’s cement this information by seeing how different apps allow you to use webhooks.

📝 How Trello Uses Webhooks

Trello is an app for managing tasks. Instead of constantly checking Trello for updates (like new cards, changes to boards, etc.), webhooks let Trello notify your app only when something important happens.

• Normally, your app would need to repeatedly ask Trello for updates, which wastes time and resources.
• Instead, Trello lets you set up a webhook — a special URL that your app provides.
• When something changes (like a new card is added or a board is updated), Trello automatically sends a message to your webhook URL with the details.

This makes your app more efficient since it only gets data when there’s something new to know.

$.post("https://api.trello.com/1/tokens/{APIToken}/webhooks/?key={APIKey}", {
  description: "My first webhook",   // A short description for your webhook
  callbackURL: "http://www.mywebsite.com/trelloCallback",  // Your webhook endpoint (where Trello will send data)
  idModel: "4d5ea62fd76aa1136000000c",  // The ID of the Trello board, list, or card you want to track
});

1. This request tells Trello, “Watch this specific Trello board (or list/card) with ID 4d5ea62fd76aa1136000000c.”
2. Trello then sends updates to the provided callbackURL whenever something changes.
3. Your webhook endpoint (e.g., /trelloCallback) should be set up to handle these incoming updates.

💬 How Slack Uses Webhooks

Slack is a popular messaging platform for teams. Instead of building a full integration, webhooks let your app send messages to Slack channels directly.

• Normally, sending messages to Slack would require complex API requests.
• Instead, Slack provides incoming webhooks — special URLs that your app can use to send messages with a simple HTTP request.
• By sending data to this URL, you can post messages, alerts, or updates in Slack channels automatically.

This makes it easy to notify Slack channels about important events, without extra complexity.

fetch("https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    text: "New order received! 🎉",
    username: "OrderBot",
    icon_emoji: ":package:"
  })
});

1. This request tells Slack, “Post a message saying ‘New order received! 🎉’ in the channel linked to this webhook URL.”
2. Slack then displays the message in the specified channel.
3. You can customize the message text, username, and even add emojis or attachments.

✨ Key Differences Between APIs and Webhooks: Summarized ✨

An important distinction between webhooks and APIs is understanding who initiates the communication and how they interact. Let’s break it down.

APIs

• An API is a set of rules that allows one app to request data or functionality from another app.
• The client sends a request (for example, GET /data) to the server, and the server responds with the data.
• The client is in control — it decides when to ask for the information.

The client requests data, and the server responds.

Webhooks

• A webhook is not something you actively call like an API. It’s a mechanism where the server sends data to the client as soon as something happens.
• The client provides the server with a URL (endpoint), and the server “calls back” to the URL when the data is ready.
• The server is in control — it decides when to send data.

The server pushes data without the client asking for it.

• Webhooks: Ideal for real-time data transfer, enabling immediate reactions to events and notifications.
• APIs: Best for on-demand data retrieval and updates.

How SuperTokens Enhances API and Webhook Security

• 🔒 Session Management: SuperTokens makes it easy to manage user sessions securely, ensuring safe communication between your app and its APIs.
• 🛡️ Token Theft Detection: SuperTokens helps prevent unauthorized access, by offering features like rotating refresh tokens and automatic token cancellation.
• 🚀 Easy to Use: SuperTokens is simple to set up, allowing developers to quickly add secure authentication to their apps.

Conclusion

APIs and webhooks are two common ways apps communicate, but they work in distinct ways:

1. APIs are like repeatedly texting your busy friend to check if they’re available for coffee — you initiate the request.
2. Webhooks are like your friend texting you when they’re free — they notify you when something happens.

APIs are ideal when you need to request data or perform actions on demand.
Webhooks excel when you want real-time updates without constant requests.

In practice, tools like Trello and Slack offer both. APIs let you create cards or send messages, while webhooks notify you of changes or new events. Choosing the right tool depends on whether you need to ask for updates or be notified automatically.

👉 Curious to dive deeper into building secure and efficient APIs? Check out these helpful resources:

1. Token-Based Authentication for APIs: What It Is and How It Works
2. Choosing the Right Authentication Provider and API for Secure Applications