Claim Check Pattern
The claim check pattern stores large payloads externally and passes a reference through the message channel, keeping messages small and channels fast while payloads live in object storage.
Definition
A claim check replaces a large message payload with a stored copy plus a reference: the sender uploads the payload to external storage, embeds the URI in the message, and receivers fetch when needed. Channels stay lightweight — brokers are optimized for small messages — and payload lifecycle becomes a separate, explicit concern with its own retention and access rules.
Context and scope
Applied when messages carry documents, images, or batches: order attachments, media processing pipelines, EDI documents over enterprise buses.
Common misconceptions
- Messages can carry whatever the broker allows — large messages degrade every consumer that must skip them and inflate broker storage
- The reference is enough — access control on the payload store must match the message security model, or anyone with the URI reads the data
- Claim check is only for blobs — any payload whose size decouples from processing — JSON batches, XML documents — benefits
Anti-patterns
- Leaking pre-signed URIs with long lifetimes into logs where anyone can harvest them
- Never expiring stored payloads and accumulating storage cost forever after messages are consumed
- Fetching the payload eagerly in every consumer regardless of use, converting message fan-out into storage stampede
Related concepts
Authoritative source
https://learn.microsoft.com/en-us/azure/architecture/patterns/claim-check
What it is
A channel is for signals; storage is for mass. Claim check separates them: the message carries the signal and a pointer; the payload waits in storage until someone actually needs it.
How it works
The producer uploads the payload to blob storage, drops the message with a reference — URI plus metadata like size and hash — and publishes. Consumers that need content fetch it, validating integrity against the hash. Retention policy ties payload lifetime to business need, not to message retention.
When to use it
Payloads beyond tens of kilobytes on high-throughput channels, fan-out where most consumers ignore the payload, and pipelines with transformation steps that need the full content once. Skip it for small messages, where the extra storage hop and fetch add latency without any broker benefit.
Pitfalls
The store becomes a coupled dependency: its outage stalls consumers even though the broker is healthy. URI security — short-lived signatures, scoped permissions — is the attack surface. Cleanup needs orchestration: consumed-but-never-deleted payloads leak, and deleted-too-early payloads break late joiners and replays.