Back to Catalog
Integration
Message Transformation
Envelope Wrapper
Wrap the payload with a metadata envelope — keep routing info separate from business data.
Intent & Description
Real-world Use Case
Outbound API call wrapped in an envelope containing requestId, authToken, source-service, destination, and timestamp headers. API gateway reads the envelope for routing and auth. Backend service unwraps and processes only the clean business payload. No auth token pollution in the domain model.
Source
📌 TL;DR
Envelope Wrapper = HTTP headers for your messages. Metadata in the envelope, business data in the payload. Keep your domain model clean from infrastructure concerns.
Advantages
- Clean separation of infrastructure concerns from business payload
- Metadata visible to routers, filters, and monitors without touching the payload
- Enables versioning and protocol negotiation in the envelope
- Standard approach aligned with CloudEvents and most broker SDKs
Disadvantages
- Adds nesting and payload size overhead
- Every component must agree on the envelope schema
- Wrapping/unwrapping logic must be applied consistently everywhere
- Easy to accidentally leak envelope fields into business logic