Payload

A payload is the data sent in the body of an HTTP request. When you POST to an API, the payload is the JSON (or form data) that carries the information the server needs to process the request. In webhooks and background jobs, the payload contains the event data or job parameters.

Payload vs headers vs URL

An HTTP request has three places to put data:

• URL / query parameters — small, visible values like IDs and filters (?page=2&sort=date)
• Headers — metadata like authentication tokens, content type, and webhook signatures
• Body (payload) — the main data content, typically JSON for APIs and webhooks

GET requests usually don't have a payload. POST, PUT, and PATCH requests almost always do.

Common payload formats

Format	Content-Type	Use case
JSON	application/json	APIs, webhooks, background jobs
Form data	application/x-www-form-urlencoded	HTML form submissions
Multipart	multipart/form-data	File uploads
XML	application/xml	Legacy SOAP APIs, some payment gateways
Plain text	text/plain	Simple notifications, logs

JSON is the standard for modern APIs and webhooks. Unless you have a specific reason to use another format, use JSON.

Payload size considerations

Payloads have practical limits:

• Web servers — Nginx defaults to 1 MB, Apache to 2 GB (but most configurations cap it lower)
• API gateways — AWS API Gateway caps at 10 MB, Cloudflare at 100 MB
• Webhook providers — most cap payloads at 1–5 MB
• Queue systems — SQS caps at 256 KB per message, Redis has no hard limit but large payloads hurt performance

If your payload exceeds the limit, the request will fail with a 413 (Payload Too Large) status code. For large data, store it externally (S3, database) and pass a reference URL in the payload instead.

Payload best practices for background jobs

• Keep payloads small — include IDs and references, not full database records. The job worker can fetch fresh data when it runs.
• Make payloads self-contained — include enough context for the job to execute without querying external state (balance small vs self-contained based on your needs).
• Include a version or type field — so consumers know how to parse the payload, especially as your schema evolves.
• Validate on receipt — reject malformed payloads early rather than failing mid-execution.

FAQ

What is a payload in an HTTP request?

The payload is the data in the request body — typically JSON — that carries the information needed to process the request. It's the "content" as opposed to the metadata (headers) and address (URL).

Do GET requests have payloads?

Technically the HTTP spec doesn't forbid it, but in practice GET requests send data via URL query parameters, not a body. Most servers and frameworks ignore or reject GET request bodies.

What happens if my payload is too large?

The server returns a 413 Payload Too Large status code. The fix is to reduce the payload size or store the data externally and reference it by URL or ID.

Payloads carry the data for webhooks, webhook events, and background jobs. They should be verified via webhook signatures when receiving external events. The server's response to a payload is indicated by an HTTP status code, and oversized payloads can cause timeouts.