For sensitive data, send a thin payload with an event type and an identifier, and let the receiver fetch details over an authenticated API. Use full payloads when data is low risk and receivers benefit from fewer calls. The Standard Webhooks spec suggests keeping payloads usually under 20 KB.
Definition
A thin webhook says what happened and which object it concerns, for example an order was updated and its id. A full or fat webhook includes the object's data in the body. Which to pick is a trade off between convenience, exposure and resilience.
What the spec says about size
The Standard Webhooks specification suggests payloads are usually smaller than 20 KB, and that for large assets you send a link instead. It is a community specification, so treat it as guidance.
Comparing the two
| Factor | Thin payload | Full payload |
|---|---|---|
| Data exposure in transit and logs | Low, just ids | Higher, the receiver's logs and proxies may store the data |
| Receiver effort | One extra authenticated fetch | None |
| Stale data risk | Low, fetch returns current state | Higher, retried deliveries may carry old data |
| Authorization | Fetch enforces current permissions | Decided at send time |
| Load on your API | Extra requests on events | None |
| Size problems | Rare | Possible for big objects |
| Signature value | Still needed for authenticity | Still needed |
Why exposure matters
A webhook body travels through the receiver's load balancers, web servers and logging tools. Anything in the body may be written to a log by a team you do not control. If the payload holds personal data, that spreads it to places you never assessed. A thin payload keeps the sensitive record behind your own access controls.
Stale data matters too. Retries can span days, per the spec. A full payload delivered on day three may describe an object that has since changed. A thin payload makes the receiver fetch the present truth.
A decision guide
- Does the object contain personal, financial or health data? Choose thin.
- Do receivers need the data within milliseconds and tolerate staleness? Full may be fine.
- Is the object large or variable? Choose thin, or send a link.
- Can receivers authenticate to your API easily? If not, thin has a cost.
- Can you offer both, with the receiver choosing per endpoint? That often suits mixed audiences.
Steps
- Classify each event type by the sensitivity of its fields.
- Default sensitive events to thin and document the fetch endpoint.
- Sign every delivery either way. See sending webhooks safely.
- Include a version and event id so receivers can deduplicate. See handling duplicates.
- Tell customers not to log full bodies for sensitive event types.
Where Safeguard fits
Safeguard's API security scanning helps review what data your endpoints return, and its compliance evidence automation helps document data handling decisions. The free scan is at https://gold.safeguard.sh/scan.
Quick check
Does a thin payload remove the need for signatures?
No. Receivers still need to know the event came from you, otherwise anyone can trigger fetches.
Is a thin webhook always better?
No. It adds a round trip. Choose by data sensitivity and receiver needs.
Sources
Last reviewed: 19 October 2026.
