# Envelope Wrapper

> Wrap the payload with a metadata envelope — keep routing info separate from business data.

- **Category**: Integration
- **Subcategory**: Message Transformation
- **Canonical URL**: https://designpattern.fyi/patterns/envelope_wrapper/

---

## Description
Clean, reusable architecture pattern.


## Use Cases
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.





## Trade-offs


### 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




### Considerations & Drawbacks

- 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







---
**Reference**: [Original Source](https://www.enterpriseintegrationpatterns.com/patterns/messaging/EnvelopeWrapper.html)