DEV Community: Muhammad Abdullah

JSON vs CSV: 7 Questions That Decide Which Format to Use

Muhammad Abdullah — Thu, 01 Oct 2026 14:07:01 +0000

Originally published on the Zento Tools Hub blog.

Short answer: use JSON when your data is nested, typed, or consumed by code (APIs, configs, document databases); use CSV when your data is flat rows and columns consumed by humans or spreadsheets (reports, exports, data cleaning). That's the whole decision in two sentences — the rest of this article is the json vs csv framework for when to use json vs csv in the edge cases, where most people get burned.

What is JSON?

JSON (JavaScript Object Notation) is a text format for structured, hierarchical data: objects (name–value pairs), arrays, strings, numbers, booleans, and null, nested freely. Every record carries its own key names, so a reader needs no external schema to interpret it. It's formally standardized in RFC 8259, which is why parsers in every language agree on what valid JSON looks like.

{
  "name": "Layla Haddad",
  "active": true,
  "orders": 14,
  "address": {
    "city": "Riyadh",
    "zip": "12213"
  },
  "tags": ["vip", "newsletter"]
}

Notice what's happening here: a boolean, a number, a nested object, and an array all live in one record. Try expressing that in a flat grid and you immediately feel JSON's reason to exist.

What is CSV?

CSV (comma-separated values) is a text format for flat tabular data: rows separated by line breaks, fields separated by commas (sometimes semicolons or tabs, depending on locale), with an optional header row. No nesting, no types, no metadata — every field is text, and interpretation is the reader's job. The closest thing to a spec is RFC 4180, which documents common practice while admitting tools interpret details differently.

name,active,orders,city,zip,tags
Layla Haddad,true,14,Riyadh,12213,"vip;newsletter"

CSV's superpower is universality: every spreadsheet, database loader, and data tool on earth reads it. Its weakness is everything it leaves unsaid — types, structure, encoding — which becomes your problem the moment data gets interesting.

The core difference between JSON and CSV: JSON is a nested tree of named values; CSV is a flat grid of rows and columns.

JSON vs CSV: side-by-side comparison

	JSON	CSV
Structure	Hierarchical: nested objects and arrays	Flat: rows and columns only
Data types	String, number, boolean, null — explicit	Everything is text; types are guessed by the reader
Self-describing	Yes — key names travel with every record	Only if a header row is present (and honored)
File size	Generally larger — key names repeat per record	Generally smaller for flat data — header written once
Human readability	Good for developers; noisy for non-technical readers	Excellent — opens directly in any spreadsheet
Parsing	Standardized (RFC 8259); parsers agree	Dialects vary: delimiters, quoting, encodings differ by tool
Streaming huge files	Possible but awkward (streaming parsers needed)	Natural — process line by line with constant memory
Comments / metadata	Not supported by the spec	Not supported either — both are pure data formats

The 7-question decision framework

Walk these in order. The first question whose answer clearly points one way usually ends the debate — that's the point of a decision framework rather than a pros-and-cons list.

1. Is the data nested or hierarchical?

If records contain objects inside objects, arrays of items, or fields that appear in some records but not others — that's JSON territory, full stop. Flattening that into CSV columns produces a sparse, unreadable mess. JSON was designed for exactly this shape.

2. Does the data type of each value matter?

Prices, quantities, true/false flags, explicit nulls: if your consumer must distinguish 42 the number from "42" the string, JSON preserves that. CSV hands everything over as text and hopes the parser guesses right — and parsers guess wrong often enough that this question alone decides many cases.

JSON remembers that 42 is a number; CSV only knows it's the characters "4" and "2".

3. Who consumes it — code or humans?

Code (APIs, apps, scripts) almost always prefers JSON: unambiguous, parsed natively in every language. Humans — analysts, accountants, clients — prefer CSV because it opens in Excel and Google Sheets with zero ceremony. When both consume the same data, pick for the primary consumer and convert for the other.

4. Is this an API or a file exchange?

APIs speak JSON: it's the default request/response format of the modern web, it's what API clients expect, and self-describing records mean clients need no separate schema. CSV appears in APIs only as a download endpoint ("export report as CSV"). Designing an API payload in CSV? Don't.

5. Is the data a simple flat table?

If every record has exactly the same fields, no nesting, and a human or a spreadsheet is involved — CSV is the honest answer. Monthly sales exports, mailing lists, bulk import files for relational databases: this is CSV's home turf, and using JSON here just adds key-name bulk for zero benefit.

For flat tabular data, CSV is usually the slimmer file — JSON repeats every key name in every record.

6. How big is the file, and how is it processed?

For large flat datasets processed row by row, CSV streams beautifully with constant memory — read a line, handle it, move on. JSON can be streamed too, but it needs a dedicated streaming parser. For nested data at scale, the format question is already answered; the question becomes how to parse it efficiently.

7. Does the toolchain have a strong opinion?

Sometimes the decision is made for you: a database's bulk loader expects CSV, a document database expects JSON, a client's ancient ERP imports only CSV. Fighting the toolchain costs more than any format's theoretical advantages. Check the destination first — the best format is often the one you don't have to convert.

5 cases where the "obvious" choice is wrong

These are the scenarios that trip people up — where instinct says one format but the right answer is the other.

1. "It's tabular, so CSV" — but columns contain lists

A customer export where each row's tags column holds "vip,newsletter,wholesale". It looks flat until someone filters by one tag — then you're parsing commas inside commas, with quoting nightmares when a value contains one. A column that routinely holds multiple values is nesting in disguise: use JSON.

2. "It's an API, so JSON" — but it's a bulk report download

A /reports/monthly-sales endpoint returning 200,000 flat rows as JSON repeats 15 key names per row — megabytes of overhead the client flattens into a spreadsheet anyway. For bulk flat downloads, a CSV endpoint is smaller and opens directly in the tool the user wants. JSON for interactive endpoints; CSV for the firehose.

3. "CSV is simpler" — but the data has no fixed schema

Event logs where each event type carries different fields. In CSV you must union every possible column (a sparse, mostly-empty grid) or maintain separate files per event type. JSON handles ragged, varying records naturally — each record carries only the fields it has. "Simpler format" isn't simpler when the data fights it.

4. "JSON is modern, so JSON everywhere" — but a human maintains the file

A price list edited by hand in a text editor. Non-developers break JSON constantly — a missing comma or quote kills the entire file, and the error messages are cryptic. A CSV opens in a spreadsheet where mistakes are visible and the structure is forgiving. Match the format to the editor's skill, not to fashion.

5. "Numbers are numbers" — but CSV ate your data

The classic: SKUs like 00123 or dates like 03/04/2026 round-tripped through a spreadsheet that "helpfully" converted them. CSV has no reliable way to say "this is text, don't touch it" that every tool honors. If exact values must survive tools you don't control, JSON's explicit string type is safer — or validate the CSV after every handoff.

Converting between JSON and CSV

You'll often need both: JSON from the API, CSV for the spreadsheet. Conversion is straightforward when the JSON is already flat — each object becomes a row, each key a column. Two caveats:

JSON → CSV loses nesting. Nested objects and arrays must be flattened (dotted keys like address.city) or serialized as JSON strings in a single cell. Either way, the CSV is a projection of the data, not a lossless copy.
CSV → JSON must guess types. Since CSV stores everything as text, the converter decides: is 14 a number? Is true a boolean? Good converters guess numbers and booleans; edge cases like zero-padded codes need a human eye afterward.

For one-off conversions, do it in the browser with a JSON ⇄ CSV converter (no uploads, no size cap). For recurring pipelines, use a proper library (Python's csv + json modules, for example) rather than hand-rolled string splitting — CSV's quoting rules punish naive parsing.

The difference between json and csv isn't which format is "better" — it's which shape your data already has and who needs to read it. Nested, typed, or machine-consumed: JSON. Flat, tabular, human-facing: CSV. Run the seven questions when it's ambiguous, watch for the five traps above, and you'll pick right every time.

Frequently asked questions

Can CSV store nested data like JSON can?
No — CSV is inherently flat: rows and columns, nothing deeper. The workarounds are flattening nested keys into dotted column names (address.city becomes address_city) or embedding a JSON string inside a single cell. The first gets unwieldy with deep nesting; the second defeats CSV's simplicity. If your data is genuinely nested, JSON is the honest choice.

Is JSON always bigger than CSV?
Not always, but usually for the same flat dataset. JSON repeats every key name in every record, while CSV writes the header row once. Pretty-printed JSON (with indentation) is bulkier still. For deeply nested data the comparison flips: CSV can't represent nesting at all, so size stops being the deciding factor.

Why do APIs return JSON instead of CSV?
Because API responses are rarely flat tables. A single response can include nested objects, arrays, mixed types, and optional fields that differ per record — all things JSON handles natively and CSV cannot. JSON is also self-describing: each record carries its key names, so a client needs no separate schema. CSV appears in APIs too, but almost always as a downloadable report endpoint, not the primary format.

Does CSV support data types?
No. Every CSV field is just text — the format has no concept of numbers, booleans, dates, or null. Whether 42 becomes a number is entirely up to the parser, and different tools guess differently. That's why a spreadsheet can silently turn the product code 00123 into the number 123. JSON distinguishes strings, numbers, booleans, and null explicitly, so types survive the round trip.

Can I open a JSON file in Excel or Google Sheets?
Not directly the way you can with CSV. Excel has Power Query (Get & Transform) and Google Sheets has add-ons that import JSON, but it's a deliberate step. If a spreadsheet is the destination, converting to CSV first is almost always easier.

Is there an official CSV specification?
Sort of. RFC 4180 (2005) documents the common CSV format and registers the text/csv MIME type — but it's informational, not a strict standard, and it admits implementations interpret the format differently. Delimiters, quoting rules, and encodings all vary between tools. JSON, by contrast, has a tight formal standard in RFC 8259 that parsers follow closely.

Should I use JSON or CSV for a database import?
It depends on the database and the data's shape. For bulk-loading flat rows into a relational database (PostgreSQL COPY, MySQL LOAD DATA), CSV is the traditional choice. For document databases like MongoDB, or records that are nested or have varying fields, JSON is natural. For a one-off human task like cleaning data in a spreadsheet, CSV wins again. Match the format to the destination, not to habit.

This article was originally published on Zento Tools Hub, where you'll find the original along with more free developer guides and tools.

What Is a Webhook? How Push-Based APIs Work (With Examples)

Muhammad Abdullah — Thu, 01 Oct 2026 14:06:06 +0000

Originally published on the Zento Tools Hub blog.

Your customer pays — and a second later, your app knows about it, marks the order as paid, and sends the receipt. Nobody on your team asked Stripe "hey, did anyone pay yet?" a hundred times a minute. Stripe told you — the moment the payment completed. That automatic push is a webhook: an HTTP callback that one service fires at another when an event happens. What is a webhook exactly, how do webhooks work, and how is a webhook different from a regular API call? This guide walks through it all: the webhook URL, a real webhook example payload, webhook vs API polling, and the security and reliability rules that separate production-grade webhooks from flaky ones.

What is a webhook?

A webhook is an event-triggered HTTP callback: when something happens in a provider's system — a payment succeeds, a commit is pushed, a form is submitted — the provider sends an HTTP POST request to a URL you registered, carrying the event's details as a JSON payload. Your endpoint receives it, does something with the data, and replies with a 2xx success response.

The mental model most developers use is the "reverse API". With a normal API, you call them whenever you want data — you initiate. With a webhook, the roles flip: they call you, but only when there's something to say. Your app never asks; it just listens. Because the trigger is an event rather than a schedule, webhooks are sometimes described as push-based communication, in contrast to polling, where the client pulls.

How webhooks work, step by step

Here's the full lifecycle, using a real Stripe payment as the example:

You register a webhook URL. In the provider's dashboard you give them an endpoint on your server, e.g. https://yourapp.com/stripe_webhooks, and choose which events to subscribe to (like payment_intent.succeeded).
The event happens. A customer completes checkout. Stripe's system records the payment and notices your endpoint is subscribed to payment events.
The provider fires an HTTP POST. Stripe sends a POST request to your webhook URL with the event details as a JSON body, plus headers like Stripe-Signature so you can verify it's genuine.
Your endpoint verifies and processes. Your handler checks the signature, parses the payload ("payment succeeded for order #123"), and updates your database or fulfills the order.
You respond with 2xx, fast. Your endpoint returns 200 promptly. That 2xx is your receipt: it tells the provider the event landed safely and no retry is needed.

Notice the economy of it: one request per event. No loops, no schedulers, no wasted calls.

The webhook URL: what it is and the rules it must follow

The webhook URL (also called a webhook endpoint) is just a route on your server that accepts POST requests — but providers are strict about what they'll deliver to:

Publicly accessible. The provider's servers must be able to reach it over the internet. localhost won't work — providers can't see your machine.
HTTPS only. Stripe and GitHub both require public HTTPS webhook endpoints, because payloads carry sensitive data. Self-signed or broken certificates will get your deliveries rejected.
Accepts POST. Webhook events arrive as HTTP POST requests. An endpoint that only allows GET will return a 405 and the delivery will fail.
Registered, not guessed. You tell the provider your URL once in their dashboard (or via their API), along with the event types you care about.

Anatomy of a webhook request

Every webhook delivery is a plain HTTP request with three parts:

Method and URL: POST /stripe_webhooks HTTP/1.1 — the provider calls your registered route.
Headers: Content-Type: application/json plus provider-specific metadata — most importantly the signature header (e.g. Stripe-Signature) your code will use to verify authenticity.
Body: the JSON payload describing the event — a unique event ID, the event type, a timestamp, and the event's data.

Here's a small, realistic example in Stripe's event shape:

{
  "id": "evt_1N4xyzABC123",
  "type": "payment_intent.succeeded",
  "created": 1696300000,
  "data": {
    "object": {
      "id": "pi_1N4xyzABC123",
      "amount": 4999,
      "currency": "usd",
      "status": "succeeded",
      "customer": "cus_1N4xyzABC123"
    }
  }
}

Everything your handler needs is right there: which event fired, when, and the object it concerns. Payloads vary by provider (GitHub sends commits and pull-request data in its own schema), but the POST + JSON + signature header skeleton is nearly universal.

Webhooks vs API polling

Before webhooks, there was only one way to find out if something changed on someone else's server: polling — asking on a schedule. "Is the payment done? Is the payment done? Is the payment done?" once a minute, forever. That's the post-office analogy: polling is walking to the post office every hour to ask for letters; a webhook is the mail carrier ringing your doorbell the instant one arrives.

The comparison is lopsided once you count the costs:

Latency: polling learns about an event only at the next check; a webhook delivers it in seconds.
Load: polling fires thousands of empty "anything new?" requests; webhooks fire exactly one request per event.
Rate limits: all those polling calls eat into your API quota; webhooks cost you nothing on the provider's API.

Polling still has its place — as a fallback if webhooks are unavailable, or when you need to backfill history. But for "tell me the moment it happens," webhooks are the designed answer.

Webhooks vs WebSockets

These get confused because both feel "real-time," but they're built for different jobs:

Direction: a webhook is one-way — the provider pushes to you, and the exchange ends there. A WebSocket is two-way: either side can send messages any time.
Lifetime: a webhook is a single HTTP request per event, then the connection closes. A WebSocket keeps one connection open for as long as both sides want to talk.
Best for: webhooks shine for discrete notifications — "a payment succeeded," "a build finished," "a row was added." WebSockets fit continuous, interactive streams — live chat, multiplayer games, collaborative editors, live dashboards.

Rule of thumb: if the conversation is a series of isolated announcements, use webhooks; if it's an ongoing dialogue, use a WebSocket.

Securing your webhooks

Your webhook URL is a public door on your server that anyone on the internet can knock on. Two things keep it safe:

HTTPS everywhere. TLS encrypts payloads in transit so payment amounts and customer IDs can't be read or altered en route. Every major provider requires it.
Verify every signature, before processing. When you register an endpoint, the provider gives you a signing secret (Stripe's starts with whsec_). Each delivery includes a signature header — an HMAC-SHA256 hash of the raw payload computed with that secret. Your handler recomputes the hash and only trusts the payload if they match, using a constant-time comparison to avoid timing attacks. Never process an unverified payload: without this check, anyone who discovers your URL could forge "payment succeeded" events.
Replay protection. Signed payloads can still be captured and re-sent by an attacker. Good providers include a timestamp in the signature scheme (Stripe does) so you can reject deliveries older than a few minutes; rejecting stale signatures closes that hole.

These secrets behave like API keys — keep them server-side, never commit them to git.

Handling failures: retries and idempotency

Webhook delivery is at-least-once, not exactly-once — and that's by design:

Respond 2xx fast. Do the verification and queue the real work; return 200 before any heavy logic. Anything else — a timeout, a 4xx, a 5xx — marks the delivery as failed.
Expect retries with backoff. Providers retry undelivered events automatically — Stripe, for example, retries for up to three days with exponential backoff. Treat every delivery as potentially repeated.
Be idempotent. Store each event's unique ID (evt_1N4xyzABC123 above) and skip events you've already processed. A retried "payment succeeded" must never double-charge or double-fulfill.
Don't depend on order. Events aren't guaranteed to arrive in the sequence they happened. Never infer "created before refunded" from arrival order — read each event's data instead.

The golden rule fits on one line: verify fast, answer 2xx immediately, and make every handler safe to run twice.

Real-world webhook use cases

Webhooks are infrastructure plumbing — once you see the pattern, you see it everywhere:

Payments (Stripe): payment_intent.succeeded fulfills the order, charge.refunded reverses it, invoice.payment_failed triggers a dunning email.
CI/CD (GitHub): a push event fires your deploy pipeline; a pull_request event runs your test suite and posts the results back.
Messaging (Slack/Discord): a deploy bot posts "v2.4 is live" to your team channel the moment the release finishes.
Commerce (Shopify): an orders/create event syncs the order into your warehouse system in real time.
Forms (Formspree/Typeform): every submission lands in your CRM or spreadsheet without a polling script.

What unites them: an event happens somewhere else, and your system needs to know immediately. That's the webhook's home turf.

How to test webhooks locally

The chicken-and-egg problem: providers need a public HTTPS URL, but you're developing on localhost. Three standard escapes:

Inspect payloads first. webhook.site gives you a throwaway URL and shows you the raw requests a provider would send — perfect for learning a payload's shape before writing code.
Tunnel your localhost. A tunneling tool like ngrok exposes your local server as a temporary public HTTPS URL you can register with the provider and receive real deliveries.
Use the provider's CLI. Stripe's CLI can forward signed test events straight to your local endpoint (stripe listen --forward-to localhost:4242/webhook), so you test signature verification end-to-end without exposing anything.

Once events flow locally, simulate the bad days too: bad signatures, duplicate deliveries, slow responses. The Stripe and GitHub dashboards both let you resend events, which makes retry behavior easy to test before it happens in production.

Common webhook mistakes

Most webhook outages trace back to one of these:

Doing the work before responding. Running a 30-second job inside the handler times out the delivery and triggers retries. Respond 2xx first, process asynchronously.
Skipping signature verification. The most dangerous shortcut. An unverified endpoint is a public "run my business logic" button.
No idempotency. Retries are normal; double-processing is a bug. Store event IDs and dedupe.
Redirects and auth on the endpoint. Stripe treats 3xx redirects to webhook requests as failures, and a login wall returns 401 — both break delivery. Webhook routes must be public and direct.
Ignoring dead endpoints. Providers eventually disable endpoints that keep failing. Watch your provider's delivery dashboard and alert on failed deliveries like any other production metric.

A webhook is the web's answer to "tell me when it happens": register a public HTTPS URL, receive each event as a signed JSON POST, answer 2xx fast, and make your handler idempotent. That loop — subscribe, push, verify, acknowledge — replaces polling for nearly every real-time integration. The authoritative references: Stripe's webhook events documentation and GitHub's webhooks documentation, both of which document the signature verification, retry, and delivery behaviors described here.

Frequently asked questions

What is a webhook in simple terms?
A webhook is an automatic message a service sends to your app the moment something happens. Instead of your app asking "did anything change?" over and over (polling), the service pushes the news to a URL you gave it (your webhook URL) as an HTTP POST request with the event details. Think of it as a "reverse API": instead of you calling them, they call you — but only when there's news.

What's the difference between a webhook and an API?
An API is the general mechanism for one program to ask another for data or actions — you call it when you want something (pull). A webhook is one specific communication pattern built on HTTP: event-driven push, where the service calls your endpoint when something happens. A webhook is a kind of API interaction, just with the direction reversed: the data provider initiates the call, not you.

What is a webhook URL?
A webhook URL is the publicly reachable HTTPS endpoint on your server that a provider sends event notifications to — e.g. https://mycompanysite.com/stripe_webhooks. You register it once in the provider's dashboard (or API), and from then on every matching event arrives as an HTTP POST request to that URL with the event details in the body.

What's the difference between webhooks and WebSockets?
Webhooks are one-way and event-driven: a provider sends a single HTTP POST to your URL when something happens, then the connection closes. WebSockets are a persistent two-way channel: client and server keep one connection open and both sides can send messages at any time, which is what live chat and multiplayer games use. Use webhooks for discrete event notifications; use WebSockets when both sides need a continuous, interactive conversation.

How do I verify a webhook signature?
Providers sign each payload with a shared secret so you know the request is genuine. The standard flow: take the raw request body (before any parsing), compute an HMAC-SHA256 hash of it using your webhook signing secret, and compare that hash with the signature the provider put in a header (e.g. Stripe's Stripe-Signature header). Use a constant-time comparison to avoid timing attacks. If it doesn't match, reject the request — never process unverified webhook payloads.

Can the same webhook event be delivered more than once?
Yes — providers like Stripe retry undelivered events for up to three days with exponential backoff, and a retry can arrive even after your first processing succeeded (e.g. you returned 500 but the work completed). That's why your handler must be idempotent: record each event's unique ID and skip duplicates instead of double-charging or double-creating records.

Do webhooks have to be HTTPS?
Effectively yes. Stripe and GitHub require webhook endpoints to be publicly accessible HTTPS URLs, because payloads often carry sensitive data (payment amounts, customer IDs). HTTP URLs aren't accepted by major providers, and using plain HTTP would expose secrets and let attackers read or tamper with event data. Serve your webhook endpoint over HTTPS with a valid TLS certificate.

How do I test a webhook locally?
Three practical options: (1) paste your payloads into webhook.site to see exactly what a provider sends, (2) use a tunneling tool like ngrok to expose your localhost with a temporary public HTTPS URL you can register with the provider, or (3) use the provider's CLI — Stripe's stripe listen --forward-to localhost:4242/webhook forwards test events straight to your local endpoint, including signed payloads.

This article was originally published on Zento Tools Hub, where you'll find the original along with more free developer guides and tools.