██FR█████ █INTELL███████████

Callbacks vs Webhooks When Working with APIs


This content originally appeared on DEV Community and was authored by Sospeter Mong’are

When building or integrating APIs, you’ll often come across two terms that sound similar: callbacks and webhooks. Both involve one system sending data back to another, but they serve different purposes. Let’s break them down.

🔹 What is a Callback Endpoint?

A callback is a URL you provide to an API when making a request. The API uses that URL to send back the result of that specific request.

  • Triggered by: A request you initiated.
  • Used for: Asynchronous responses.
  • Scope: Only for the request that included the callback URL.

👉 Example:
You send a fund transfer request to a banking API (like KCB Buni). Because transfers take time to process, you provide a callback URL (https://yourapp.com/ft-callback). Once the bank finishes processing, it POSTs the result (success or failure) to that callback.

{
  "transactionStatus": "SUCCESS",
  "amount": 100,
  "transactionReference": "CSS472TCP"
}

✅ Purpose: Tie back the outcome of a request you made earlier.

🔹 What is a Webhook?

A webhook is different. Instead of being tied to a single request, it’s an ongoing subscription to events. You tell the API provider, “Whenever this event happens, send the details to this URL.”

  • Triggered by: An event in the provider’s system.
  • Used for: Real-time notifications.
  • Scope: Continues to work until you unsubscribe.

👉 Example:
With M-Pesa C2B, you register a webhook endpoint like https://yourapp.com/mpesa-callback. Every time a customer sends money to your paybill, M-Pesa automatically sends a notification to that URL — no request needed from you.

{
  "TransactionType": "Pay Bill",
  "TransID": "QW234F",
  "TransAmount": "250.00",
  "MSISDN": "254712345678",
  "BillRefNumber": "INV1023"
}

✅ Purpose: Keep your system in sync with external events in real-time.

🔹 The Key Difference

  • Callback endpoint → “Tell me the result of this specific request.”
  • Webhook → “Notify me whenever this event happens.”

🔹 Real-World Analogy

Imagine a restaurant:

  • Callback: You place an order online and provide your number. They call you when your order is ready.
  • Webhook: You subscribe to their menu updates. They text you every time they add a new dish, even if you didn’t order anything.

🔹 Why It Matters for Developers

When working with APIs:

  • Use callbacks when your request may take time and you need the outcome.
  • Use webhooks when you want to react automatically to events you didn’t directly trigger.

In practice, many APIs use both. For example, a payments API may:

  • Send a callback with the result of your initiated payment.
  • Offer a webhook for general payment notifications (refunds, reversals, failed debits).

🔹 Best Practices

  1. Secure your endpoints
  • Validate request signatures or whitelist provider IPs.
  • Store raw payloads before processing (helps debugging).
  1. Make endpoints highly available
  • Providers often retry if your server is down, but don’t rely on it.
  1. Log everything
  • Keep track of incoming notifications to resolve disputes later.

✅ Final Takeaway

  • Callback = one-time, request-based response.
  • Webhook = ongoing, event-driven notification.

Both are critical in modern API development — understanding the difference helps you design more reliable integrations.


This content originally appeared on DEV Community and was authored by Sospeter Mong’are