DEV Community: CHRISTIAN OTIENO

REST APIs vs. Webhooks: Architecture, Trade-Offs, and Real-Time Use Cases

CHRISTIAN OTIENO — Mon, 21 Sep 2026 12:52:35 +0000

Picture this: You run a food delivery app. A customer places an order, and they want to know the exact second the driver picks up their food.How do you update your system?
Approach A: Your backend asks the restaurant's server every 3 seconds: "Is it ready? Is it ready? Is it ready?"

Approach B: You tell the restaurant: "Hey, here's my phone number. Text me the instant the driver picks up the order."

Approach A is polling a REST API. Approach B is a Webhook.While both rely on HTTP, they represent opposite architectural paradigms: Request-Driven (Pull) vs. Event-Driven (Push).

In this article, let’s break down the mechanics, dissect real-world production use cases, and examine the hard engineering challenges (security, idempotency, and retry storms) you must solve when moving to event-driven architectures.

The Core Mechanical Difference

**
The fundamental difference comes down to who initiates the communication and when data moves.

POLLING (REST API) EVENT-DRIVEN (WEBHOOK)

Client Server Consumer Provider
| | | |
|--- GET /status --->| | (Idle - 0 reqs) |
|<-- "pending" ------| | |
| | | |
|--- GET /status --->| | [Event Occurs] |
|<-- "pending" ------| | (Payment Success) |
| | | |
|--- GET /status --->| |<-- POST /webhook --|
|<-- "completed" ----| |--- 200 OK -------->|
v v v v

REST APIs: The "Pull" Model

In a standard REST architecture, the client is always in the driver's seat:

The client establishes a TCP/TLS connection to an endpoint.
It sends an HTTP verb (GET, POST, PUT, DELETE).
The server processes the request synchronously and returns a response.

If you need to know when state changes, you must poll. Polling creates massive overhead: up to 98% of periodic polling calls return empty or unchanged state, burning CPU cycles, database queries, and bandwidth on both sides.

Webhooks: The "Push" Model

**
A webhook (often called a "reverse API" or HTTP callback) flips the relationship:

The consumer exposes a public HTTPS endpoint (e.g., https://api.myapp.com/webhooks/stripe).
The consumer registers this URL with the provider service.
When a state change happens inside the provider (e.g., a payment succeeds, a git branch merges), the provider dispatches an HTTP POST request containing the event payload to the consumer's endpoint.

2. Head-to-Head Comparison Matrix

Dimension REST API (Client Pull) Webhooks(server/push)

Initiator Client triggers request Server triggers callback on event
Latency Bounded by poll rate Real-time / Sub-second

Network Overhead High Minimal
Consumer Egress only Must expose a public, high-
Infrastructure availability ingress URL

Failure Handled on client Handled by provider Recovery schedule via retry queues.
logic
Handled by provider queues exponential with exponential backoff

3. Real-World Production Use Cases

When building scalable systems, you rarely pick just one. Production microservices typically combine both. Here are three common patterns:

Use Case 1: Payment Gateways (Stripe, PayPal, Adyen)

The Problem: Card authentications (3D Secure), ACH transfers, or asynchronous bank debits don't resolve in 200ms. They can take 15 seconds, 2 hours, or 3 banking days.
The Architecture:

Your frontend uses a REST API to initiate the transaction (POST /v1/payment_intents).
You give your user a pending state without locking up your server threads waiting on banking clearinghouses. 3.Days or seconds later, Stripe hits your Webhook endpoint with payment_intent.succeeded. 4.Your receiver updates the database and provisions the digital product.

_// Express.js Webhook Receiver for Stripe
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['stripe-signature'];
let event;

try {
// 1. Verify that the request actually came from Stripe
event = stripe.webhooks.constructEvent(req.body, sig, process.env.STRIPE_WEBHOOK_SECRET);
} catch (err) {
return res.status(400).send(Webhook Error: ${err.message});
}

// 2. Handle specific asynchronous domain event
if (event.type === 'payment_intent.succeeded') {
const paymentIntent = event.data.object;
fulfillOrder(paymentIntent.id);
}

// 3. Immediately return 200 OK so the provider stops retrying
res.json({ received: true });
});_

Use Case 2: CI/CD Pipelines (GitHub & Jenkins/CircleCI)

1. The Problem: Imagine running a build server that queries 1,000 repositories every 5 seconds to check if developers pushed new commits. You'd hit GitHub's API rate limits in minutes.The 2. {}YTArchitecture:

Developers push commits to GitHub via Git/SSH.
GitHub dispatches a push webhook payload containing commit metadata directly to your CI/CD ingress.
CI runners spin up ephemeral Docker containers within milliseconds of the merge.

Use Case 3: IoT Fleet Tracking & Delivery Notifications

**
The Problem: A delivery driver sends GPS coordinates every 2 seconds. A user only cares when the driver is within 200 meters of their door.
The Hybrid Pattern:

REST API: Used when the consumer opens the app and queries historical routes (GET /trips/42/route).
Webhooks: The telematics engine monitors the vehicle's geofence. Once the geofence is breached, it pushes a webhook event (shipment.approaching), which triggers a push notification to the customer's smartphone. **

4. The Engineering Gotchas (What Breaks in Production)

**
Webhooks sound magical until you deploy them at scale. Here are the three critical engineering problems you must solve:

Security & Signature VerificationAnyone who discovers your public webhook endpoint can send fake payloads to trick your app into shipping free products or corrupting state. ** > Solution**: Providers sign the outgoing request with a shared secret using HMAC-SHA256. Always verify the incoming cryptographic signature header before touching the payload body.
At-Least-Once Delivery & IdempotencyWhat happens if your server takes 5.1 seconds to process an event, but the provider times out at 5.0 seconds? The provider assumes the payload was lost and retries the webhook.If your code doesn't guard against duplicates, you might charge a customer twice or send two confirmation emails. Solution: Make your webhook handlers idempotent. Track unique event IDs in a cache or database with unique constraints:

_async function handleWebhook(event: WebhookEvent) {
// Check if we've already processed this event ID
const isDuplicate = await redis.set(evt:${event.id}, 'locked', 'NX', 'EX', 86400);

if (!isDuplicate) {
// Already processed or currently processing
return { status: 'ignored_duplicate' };
}

await processBusinessLogic(event);
}_

3. The Slow Consumer Problem (Avoid Timeouts!)

**
If your webhook handler runs database migrations, calls external APIs, and generates PDFs before returning an HTTP response, the provider will timeout and retry the request repeatedly—triggering a retry storm that can crash your server.

*Solution: **Return 200 OK immediately. Ingest the payload, push it onto an internal queue (RabbitMQ, SQS, Redis BullMQ, or Kafka), and let asynchronous background workers process the job.
*

Summary: When to Use Which?

**
Choose a REST API when:

You need synchronous, immediate confirmation (e.g., login authentication, search queries, CRUD operations).
Your client runs on mobile or web browsers behind carrier NATs where public incoming ports cannot be opened.
You need granular querying, pagination, or filtering parameters.
Choose Webhooks when:
You need real-time, event-triggered action across distinct microservices or third-party platforms.
Operations take variable or prolonged periods to complete.
You want to reduce idle compute waste and eliminate unnecessary polling loops.

What architecture are you currently running? Have you had to migrate a polling service over to webhooks or WebSockets? Let's discuss in the comments below!

Demystifying JWTs: What Actually Happens Under the Hood published: true tags: webdev, security, javascript, architecture

CHRISTIAN OTIENO — Mon, 14 Sep 2026 16:11:44 +0000

JSON Web Tokens (JWTs) are practically everywhere. We reach for them when building microservices, mobile APIs, and single-page apps.

Yet when asked how they actually work under the hood, the standard developer answer usually defaults to:

"It's a signed string you store in localStorage and pass along in an Authorization header."

Let’s dismantle that abstraction. A JWT is not encrypted by default, it is rarely magic, and implementing it blindly introduces real security headaches.

Here is what is actually going on under the hood.

The Anatomy of a JWT
A JWT is fundamentally a single string divided into three distinct segments separated by dots (.):

Plaintext

header.payload.signature
_
Every segment is encoded using Base64Url—not encrypted. Anyone who intercepts the token can paste it into an online decoder and inspect the data instantly.

Let’s break down the three parts.

The Header The header contains metadata about the token: the type and the cryptographic algorithm used to secure it.

JSON
{
"alg": "HS256",
"typ": "JWT"
}

alg: The signing algorithm (e.g., symmetric algorithms like HS256, or asymmetric key pairs like RS256).
typ: Almost universally set to "JWT".
The Payload
The payload contains the claims—statements about the user and context the server needs to function statelessly.

JSON
{
"sub": "usr_94810284",
"name": "Jane Doe",
"role": "admin",
"iat": 1711926000,
"exp": 1711929600
}
Claims fall into two primary buckets:

Registered claims: Standardized keys like sub (subject/user ID), iat (issued-at timestamp), and exp (expiration timestamp).

Custom claims: Application-specific context like role, tenant_id, or access scopes.

⚠️ Critical Security Rule: Never store sensitive data (passwords, private API keys, or unencrypted PII) inside a JWT payload. Encoding is not encryption.

The Signature This is the integrity anchor of the entire token. The signature prevents tampering.

To generate it, the issuing server takes the Base64Url-encoded header, appends the Base64Url-encoded payload, and hashes them using a private secret:

JavaScript
const signature = HMACSHA256(
${base64UrlEncode(header)}.${base64UrlEncode(payload)},
SERVER_SECRET_KEY
);
When a client sends the token back, the server re-runs that exact calculation. If the newly calculated signature matches the signature attached to the token, two things are guaranteed:

Integrity: The header and payload were not altered in transit.

Authenticity: The token was issued by an entity holding the secret key.

The Lifecycle of a Stateless Request
Here is the complete authentication flow in practice:

[ Client ] [ Server ]
| |
|---- 1. POST /api/login (Credentials) ------------->|
| |-- Validates credentials
| |-- Signs JWT with secret
|<--- 2. Returns JWT (Set-Cookie / Body) ------------|
| |
|---- 3. GET /api/dashboard (Bearer ) ------->|
| |-- Recomputes signature
| |-- Checks exp timestamp
| |-- Serves data (Zero DB lookups!)
|<--- 4. HTTP 200 OK --------------------------------|
Authentication: The client submits credentials to /api/login.

Issue: The server checks credentials against the database, builds the claims payload, signs it with its secret, and returns the token.

Storage: The client stores the token (preferably in an httpOnly, Secure, SameSite cookie to mitigate XSS attack vectors).

Transport: Subsequent calls pass the token via the Authorization header:

HTTP
Authorization: Bearer eyJhbGciOi...
Stateless Verification: The server recomputes the signature using its secret and checks the exp timestamp. If valid, the request proceeds—without querying a session database.

Architectural Trade-offs: When NOT to Use Pure JWTs
Statelessness makes horizontal scaling easier, but it introduces tradeoffs that standard tutorials gloss over:

Feature Session IDs (Stateful) JWTs (Stateless)
Revocation Instant (delete record from Redis/DB). Difficult (valid until exp triggers).
Payload Size Tiny (~32-character pointer string). Larger (carries claims on every request).
DB / Cache Load Hit on every authenticated request. Zero DB lookups for validation.
Server Sync Requires shared session store. Any service with the key/public key can verify.
The Revocation Problem
If a user changes their password, reports a compromised account, or gets suspended, an issued JWT remains completely valid until its exp time passes.

To fix this in production, architectures commonly use:

Short-lived access tokens (5–15 minutes) combined with stateful refresh tokens stored securely in a database.

Revocation blocklists in Redis (which sacrifices pure statelessness).

Core Takeaways
Base64Url is encoding, not encryption. Don't hide secrets in the payload.

Signatures ensure integrity, not secrecy. They only prove the data hasn't been modified.

Statelessness is a double-edged sword. Build an explicit revocation strategy before relying on JWTs in production.

Over to you: How does your team handle token invalidation? Are you pairing short-lived access tokens with refresh tokens, or relying on centralized session stores like Redis? Let's discuss in the comments below!

Beyond the Monolith: A Practical Guide to Database Sharding

CHRISTIAN OTIENO — Sat, 29 Aug 2026 10:37:56 +0000

Table Of Contents
1.Introduction: When Scaling Up Hits a Wall
2.What Is Database Sharding?
3.Core Sharding Architectures & Routing Strategies
4.The Operational Hidden Costs of Sharding
5.When Should You Actually Shard?
6.Conclusion

Introduction: When Scaling Up Hits a Wall

Every growing application eventually hits a point where vertical scaling—throwing more CPU, RAM, and faster NVMe drives at a single database instance—stops being economically or physically viable. When your primary relational database hits storage limits, IOPS bottlenecks, or connection pool saturation, horizontal scaling becomes the inevitable next step.

Enter database sharding.

While sharding solves massive throughput and storage constraints, it introduces a whole new class of distributed systems complexities. Let's break down how sharding actually works, the architectural patterns you can choose, and the hidden operational costs you need to weigh before splitting your data.

What Is Database Sharding?

At its core, sharding is a shared-nothing horizontal partitioning strategy. Instead of keeping all rows of a massive table in a single database instance, you split the rows across multiple independent databases (called "shards").

Each shard holds a subset of the total data, and the union of all shards makes up the complete dataset.

           [ Application / Router Layer ]
          /              |              \
         /               |               \
        v                v                v
  [ Shard 1 ]      [ Shard 2 ]      [ Shard 3 ]
 (Users A-H)      (Users I-P)      (Users Q-Z)

Unlike read replicas (which duplicate the entire dataset for read scaling), shards actively partition write and storage workloads, allowing your infrastructure to scale out linearly.

Core Sharding Architectures & Routing Strategies

How do you decide which shard a piece of data belongs to? Your routing strategy dictates how queries find their target nodes.

Range-Based Sharding

Data is partitioned based on predefined ranges of a column value. For example, user IDs 1 to 1,000,000 go to Shard A, and 1,000,001 to 2,000,000 go to Shard B.

Pros: Simple to implement; highly efficient for range queries (e.g., WHERE created_at BETWEEN ...).
Cons: Prone to hotspotting. If most of your incoming traffic targets newly created users, Shard B will absorb 90% of the write load while older shards sit idle.

Hash-Based Sharding

An application or database proxy passes a sharding key (like a user_id or tenant_id) through a hash function (such as MurmurHash), and applies a modulo operation to determine the target shard index.

Conceptual hash routing example

shard_count = 4
user_id = 849203
shard_index = hash(user_id) % shard_count
Pros: Evenly distributes data and write load across all available shards, eliminating hotspots.
Cons: Extremely painful to scale out. If you add a fifth shard, changing the modulo math requires a massive data migration (re-sharding) to redistribute existing keys. (Consistent hashing algorithms help mitigate this, but add architectural overhead).

Directory-Based Sharding

You maintain a centralized lookup table (or service) that tracks which entity lives on which shard.

Pros: Highly flexible; you can manually move individual tenants or users to different shards for load balancing.
Cons: The directory lookup becomes a single point of failure (SPOF) and an extra network hop for every single query.

The Operational Hidden Costs of Sharding

Before you commit to sharding your database, you must accept the distributed systems trade-offs. Sharding breaks several guarantees that monolithic SQL databases provide out-of-the-box:

Cross-Shard Joins are Painful: If users live on Shard 1 and their corresponding orders live on Shard 2, joining those tables requires application-level orchestration, scatter-gather queries, or distributed transactions (two-phase commit), which heavily degrades performance.

Global Uniqueness Constraints: Enforcing a unique constraint (like an email address or username) across multiple independent databases requires a centralized ID generation service (like Twitter Snowflake or centralized Redis counters).

Re-balancing and Resharding: As your data grows unevenly, splitting an overloaded shard into two requires careful planning, dual-writes, and zero-downtime data migration pipelines.

When Should You Actually Shard?

The golden rule of database sharding is simple: Don't do it until you absolutely have to.

Exhaust all other optimization paths first:

Optimize your indexing and query execution plans.
Implement aggressive caching layers (e.g., Redis or Memcached).
Offload read traffic using read replicas.
Purge or archive cold/historical data into cheaper cold storage.
If you have genuinely maxed out vertical scaling, saturated your primary write IOPS, and your dataset spans hundreds of gigabytes or terabytes where partitioning by tenant makes logical sense—then sharding is your answer.

How does your team handle database scaling bottlenecks? Have you ever migrated a monolith to a sharded architecture, and what was your biggest lesson learned? Let me know in the comments below!

AI Can Build Your UI—But Can It Maintain It?

CHRISTIAN OTIENO — Wed, 17 Jun 2026 17:42:02 +0000

AI coding agents have moved way past simple autocomplete. Anyone can prompt an agent to build a clean dashboard component. But what happens six months later when dependencies shift, state management gets tangled, or accessibility breaks?

ASCII ART

CHRISTIAN OTIENO — Wed, 17 Jun 2026 17:29:45 +0000

Why ASCII Art is Still the Ultimate Dev Nostalgia.
If you’ve ever opened a new terminal tool, checked a repository's README.md, or looked closely at a well-documented source code file, chances are you’ve run into ASCII art.

While it feels like a relic of the 1980s BBS board era, this text-based design medium is still alive, kicking, and surprisingly practical in modern development.

What is ASCII Art?
At its core, ASCII art is a graphic design technique that uses printable characters from the ASCII standard (letters, numbers, and symbols like /, \, |, _) to piece together visual images.

Before high-resolution displays and modern GPUs, this was how developers added personality, logos, and diagrams to text-only screens.

Why Do Developers Still Use It?
Zero Overhead: It requires no image hosting, no external assets, and zero loading time. It’s just plain text.

Terminal Branding: Popular CLI tools (like Homebrew, Docker, or Neofetch) use ASCII splash screens to build an instant, recognizable brand right in your terminal.

Code Organization: Massive codebases sometimes use giant ASCII headers to separate major sections in a single source file, making it easy to spot sections while scrolling fast.

Pure Nostalgia: Let’s honest—it just looks incredibly cool and gives off peak hacker vibes.

Quick Tools to Generate Your Own
You don’t have to manually type out every backslash. Here are the quickest ways to add some flavor to your next project:

FIGlet: A classic command-line tool that turns ordinary text into large, stylized ASCII banners.

TAAG (Text to ASCII Art Generator): An awesome web-based tool with hundreds of fonts to preview your text instantly.

Image-to-ASCII Converters: Tools like jp2a can take an actual .jpg or .png logo and translate it into a grayscale-like block of text.

The Takeaway
ASCII art is a bridge between computing's past and present. Next time you build an open-source tool, consider throwing a custom ASCII logo into your README or CLI startup script. It’s a small, fun touch that shows you care about the details.

Do you use ASCII art in your project configs or CLIs? Drop your favorite generator or your terminal setups in the comments below!