Webhooks vs. API: a webhook pushes, an API waits to be asked

Webhooks vs. APIs: what's the difference

An API is pull-based. Your app decides when to ask. It sends a request and gets back the current state. Nothing arrives until you ask for it.

Say you want to know about a change the instant it happens. You have to keep asking. That's called polling. Polling works, but it has a cost. Every poll that finds no change is a wasted request. The delay before you notice a real change is always at least as long as your poll gap.

A webhook flips the direction. The CMS tells your app the instant something changes. Not the other way around. You register a URL and a set of events you care about. Draftbase sends a request to that URL the moment a matching event fires. No interval to tune. No idle loop to run.

Webhooks don't replace the API. They remove the need to poll for writes. You still need an API for reads. A webhook only tells you that something changed. It doesn't hand you the full state of your system. For that, you go back to the API.

Here's a real example. Say you cache a rendered blog post at the edge. Without webhooks, you have two options. Set a short cache time and poll for fresh data. Or accept stale content until the cache expires on its own. With a webhook on entry.published, you clear that one cache entry the moment the edit goes live. No guesswork, no wasted polling.

How Draftbase implements webhooks

Webhook dispatch runs after a write already succeeded. Not as part of it. When an entry is created, updated, or changes status, Draftbase checks which webhooks are subscribed. It matches on environment and template. Then it sends each match a signed request. If a subscriber is slow or offline, the write itself is unaffected. Dispatch runs off to the side. Failures get logged, not shown to the editor.

This split mirrors the same design as the rest of Draftbase. Write and read are separate surfaces. Wiring up a webhook never touches your read path. Revoking a webhook never affects your delivery API keys.

A webhook can also scope itself to one environment or one template. That matters once a project has more than one team publishing content. A Slack webhook for marketing doesn't need to fire on every product update too.

Every delivery carries an event ID, an event name, and a timestamp. Your endpoint can use the event ID to skip a repeat. That matters if a retry lands after the first attempt already worked, but timed out before Draftbase saw the reply.

Entry payloads can include the before-and-after values for the change. Not just a bare notice. That's a setting per webhook. Turn it on if your endpoint needs the actual diff. Leave it off to keep the payload small.

Webhooks vs. API polling

The table below lines up three setups on the same four points. Polling the API on a timer. A generic CMS's webhooks. And Draftbase's. The gap between polling and webhooks is the biggest jump. The gap between a generic webhook and a Draftbase one is mostly about defaults.

The setup row hides how much the real work changes. A polling script has to fetch, check against the last known state, and store that state somewhere. A webhook keeps no state on your side. Draftbase already knows what changed. It tells you directly. You don't have to work it out yourself.

The server-load row also grows at scale in a way the table can't show. A poll gap that's fine for one app becomes real load once ten apps poll the same API on their own clock. Most polls find nothing new, most of the time. A webhook only fires when there's something to say. That cost doesn't grow the same way as the number of listeners grows.

When to use webhooks vs. the delivery API

Use the delivery API for reads. When a page loads, pull the current state directly. That's what the API is for. It's the only source that gives a full, correct snapshot at that exact moment. A webhook is a point-in-time event, not a live view.

Use webhooks to react to change. Common cases: clear a cache, update search, post a Slack alert, or kick off a build. In every one of those cases, you don't need the full entry on every event. You just need to know something changed.

Most real setups use both together, not just one. A typical setup pulls state on render through the delivery API. And reacts to change in the background through a webhook. Neither one alone covers both jobs well.

A site rebuild is the clearest case of this. The build pulls every entry it needs through the delivery API. That's a read. It wants one full, correct snapshot. What triggers the build is a webhook on entry.published. It fires the build the moment an editor ships a change. Not a rebuild on a fixed timer.

Why the push model is winning

API-first design is now the default for how teams build. Not the exception. 83.2% of teams now call themselves API-first. That's up from 74% in 2024. (Source) That shift makes webhooks a default choice, not a bolt-on.

The webhook side of that shift is well underway too. Especially at big firms running many linked systems. 78% of Fortune 500 firms now run setups where webhooks are a main pattern. That's up from about 51% in 2021. (Source) Here, that means an API for reads and webhooks for change alerts, running side by side. Neither one replaces the other.

Draftbase's webhooks follow that same pattern by default. The delivery API and the webhook stream are built as one system. Not two products stitched together after the fact.

Neither stat is specific to content tools. Both describe patterns broadly. But the trend fits here too. Teams now expect a content tool to notify them of change. Not make them build a polling layer just to stay in sync.

Vendor lock-in here is low. A webhook is a plain signed request. Switching CMS vendors later doesn't mean rewriting your core logic — only the URL you register and the header you check.