REST APIs & Webhooks
Pull when you need to, push when it matters.
REST APIs let you query for data when you want it. Webhooks let systems tell you the moment something changes. The right architecture uses both — REST for intentional reads and writes, webhooks for event-driven reactions. Build the plumbing right and every SaaS in your stack talks natively.
REST polling · Pull model
GET /api/orders every 15s
Request timeline — 5 minutes
Requests
20
With data
1
Wasted
95%
Polling tradeoff: Client controls request timing, but most requests waste bandwidth and rate-limit quota. Latency = poll interval (up to 15s here).
Webhook · Push model
POST /webhook/orders
Delivery with retry-on-fail
1
+0s
Server overloaded
500
2
+1s
Still failing
500
3
+2s
Retry 3
500
4
+4s
Delivered
200
Latency
~140ms
Requests
1
Delivered
✓
Webhook tradeoff: Server controls delivery; instant latency, no wasted requests. Need HTTPS endpoint on your side + retry logic + signature verification.
Use both: REST for reads + writes you initiate; webhooks for events you need to react to instantly.
Pick the right model
REST vs Webhooks — when each fits.
Use REST (pull) when...
- You need data on-demand in response to user actions
- Creating / updating / deleting records (mutations)
- Querying with filters, pagination, or search
- Running scheduled jobs (nightly reports, sync)
- Small number of consumers controlling their own request timing
- Request-response is the natural shape of the interaction
Use Webhooks (push) when...
- You need to react the moment an event happens
- Events are relatively infrequent (seconds to hours between)
- Many consumers want to know about the same event
- Latency matters more than control over timing
- The source system wants to minimise API load
- You can expose a public HTTPS endpoint to receive them
Real-world pattern: Most production integrations use both. Webhooks for event-driven reactions ("payment succeeded → fulfil order"), REST for everything else ("user requested report → query + build it"). Don't pick one — use the right one per use case.
Auth patterns
How APIs are actually authenticated — the 4 patterns.
Every API protects access somehow. Knowing which pattern the API uses is the first step when integrating. Here's what you'll encounter, with honest tradeoffs for each.
API Key (header)
Authorization: Bearer sk_live_xxxxx
Good for
Simple to implement, easy to rotate, fine for server-to-server.
Limits
Anyone with the key has full access. Don't embed in client-side code. No expiry by default.
When you'll meet it
Most SaaS APIs (Stripe, SendGrid, Airtable, HubSpot for server-to-server).
OAuth 2.0
Authorization: Bearer <short-lived JWT>
Good for
User-level consent, scoped permissions, tokens expire, refresh tokens for re-auth.
Limits
More complex flow to implement. Token refresh logic needed. Callback URL management.
When you'll meet it
Google APIs, Microsoft 365, Zoom, Slack apps accessing user data.
HMAC-signed requests
X-Signature: sha256=<hash of body+secret>
Good for
Prevents tampering in transit. Secret never sent over wire. Verifiable origin.
Limits
Library support varies. Must coordinate secret rotation across sender + receiver.
When you'll meet it
Webhooks from Stripe, GitHub, Shopify, Slack — ensures sender is who they claim.
Basic Auth + HTTPS
Authorization: Basic base64(user:pass)
Good for
Universally supported, zero learning curve. Works when nothing else does.
Limits
Sends credentials every request. If endpoint isn't HTTPS, credentials leak.
When you'll meet it
Legacy APIs, internal tools, some older banking/ERP systems.
Webhook receiver checklist
If you're receiving webhooks, these aren't optional.
Webhooks look simple but there are 6 things that trip up teams every time. Missing any of these causes production incidents.
Verify signatures
Every respected webhook sender signs the payload (Stripe: Stripe-Signature, GitHub: X-Hub-Signature-256). Always verify — otherwise anyone can forge events to your endpoint.
Return 200 fast
Respond within 5 seconds or senders mark delivery failed and retry. Acknowledge first, then do work async via queue. Slow responses = duplicate events.
Be idempotent
Senders retry on failures. Same event may arrive twice. Deduplicate via event ID. Processing a "payment succeeded" twice = double-charge your logic.
Handle event ordering
Webhooks may arrive out-of-order. Don't assume "created" arrives before "updated". Use event timestamps + reconcile state rather than trust order.
Log everything
Store raw payloads of every webhook for 30+ days. When "something went wrong at 3am Thursday", you need the actual bytes to debug. Compliance sometimes requires this.
Dead-letter the failures
After N retries, senders stop. Move failed events to a dead-letter queue you monitor. Don't silently drop. Set up alerts — you WILL want to replay later.
Before writing code
When custom API integration is the wrong answer.
Zapier/Make already supports both apps
If off-the-shelf tools cover the integration, using them costs €10-100/mo. Building + maintaining equivalent code costs €5k-20k upfront + ongoing. Do the maths.
One-off data migration
Moving data once between systems? Use n8n / CSV export-import / quick script. Don't architect a reusable integration for a single-use job.
You have no one to maintain it
Custom code rots when APIs change (they do, every 6-12 months). Without someone owning it, you're setting up a future break. Zapier's upgrades are on Zapier.
Integration needs are changing weekly
Custom code slows iteration. If requirements haven't settled, prototype in Zapier/Make. Freeze into code only when shape is stable.
The source API is unstable/documented poorly
Fighting a bad API + maintaining glue code + handling their breaking changes = hell. Delay custom integration until the third-party API is mature.
Volume is genuinely low
< 1000 events/day almost never justifies custom. Zapier's free tier or a single-scenario Make account handles this. Save code for problems that actually warrant it.
Frequently asked
REST + Webhook questions.
Rule of thumb: if the volume justifies €500+/mo in Zapier costs OR the logic is too complex for a visual tool OR it needs sub-second latency — go custom. Below those thresholds, Zapier/Make is cheaper total-cost-of-ownership once you factor in maintenance.
Related
Related integration tools
Need systems talking to each other reliably?
60-minute technical scoping call. We'll map your systems, identify where REST vs webhooks fit, spec the integration architecture. Honest recommendation on custom vs Zapier/Make based on your volume and complexity.