Skip to content
Software Architecture Guide

Claim Check

Explanation

Section titled “Explanation”

Messaging systems work best with many small messages. They often limit message size. Large messages risk rejection and can slow the system down.

Claim Check avoids this. The sender writes the payload (the large data) to an external store. It then sends a message that holds only a reference to that payload. This reference is the claim check. Receivers use it to fetch the payload directly from the store.

The goal is to shrink the message without losing information. The data is stored persistently, and the claim check travels onward in its place.

Relation to other patterns. A Content Filter removes data permanently. Claim Check removes fields only temporarily, because the data stays in the store. Another component can later use a Content Enricher to fetch the stored data with the claim check. Both are covered in the article Content Enricher and Content Filter.

Design points to settle:

  • Lifecycle. Decide who owns the payload’s lifecycle. Coordinate message expiry with payload retention. Otherwise a valid claim check may point to deleted data.
  • Write order. Writing the payload and publishing the claim check happen in separate systems. They are not one atomic (all-or-nothing) transaction. This can leave orphaned payloads or claim checks that resolve to nothing. Publish the claim check only after the write succeeds.
  • Integrity. If consumers must verify the payload, put a content hash or digital signature in the message. Also define what happens on a mismatch.
  • Security. Do not embed security tokens in the claim check. The store enforces its own access controls. Keep sensitive data out of the messaging path.

Cloud use. Azure samples pair Blob Storage with messaging systems such as Queue Storage, Event Hubs, and Service Bus. They use Event Grid blob URLs as the claim check.

Example

Section titled “Example”

A system sends scanned documents between two services. The sending service saves each scan in a shared store. It then publishes a short message with a reference to the scan. The receiving service reads the reference, fetches the scan from the store, and processes it. If it must check the scan, it compares a hash carried in the message.

Trade-offs

Section titled “Trade-offs”
  • Latency. Receivers make extra network trips compared with inline delivery.
  • Dependency. The system now relies on the external store’s availability and durability.
  • Consistency. Message and payload live in separate systems, so they can drift apart. Orphaned payloads and unresolvable claim checks are possible.
  • Ownership. Someone must own payload cleanup and align it with message expiry.

The sender stores the payload first, then sends only the claim check.

Diagram source 
sequenceDiagram
  participant S as Sender
  participant D as Data store
  participant Q as Message channel
  participant R as Receiver
  S->>D: 1. Write payload
  D-->>S: Write succeeded
  S->>Q: 2. Send claim check
  Q->>R: 3. Deliver claim check
  R->>D: 4. Fetch payload with claim check
  D-->>R: Payload

Checks

Section titled “Checks”
  • The document names who owns the payload lifecycle and aligns message expiry with payload retention.
  • The claim check is published only after the payload write succeeds.
  • Security tokens are not embedded in the claim check; the store enforces its own access control.
  • Where integrity matters, messages carry a hash or signature and a mismatch protocol is defined.
  • The external store’s availability and added latency are acknowledged as risks.
Section titled “Related”

Sources

Section titled “Sources”