SOAP headers and the WS-* standards

Headers carry everything that is not the business payload: correlation, addressing, security and routing, with their own processing rules.

Header blocks and mustUnderstand

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:wsa="http://www.w3.org/2005/08/addressing">
  <soap:Header>
    <wsa:To>https://example.com/orders</wsa:To>
    <wsa:Action>urn:example:orders/PlaceOrder</wsa:Action>
    <wsa:MessageID>urn:uuid:0d5f...-b1</wsa:MessageID>
    <wsa:ReplyTo>
      <wsa:Address>https://client.example.com/acks</wsa:Address>
    </wsa:ReplyTo>
    <TraceId soap:mustUnderstand="1"
             xmlns="urn:example:telemetry">7f3c9a1e</TraceId>
  </soap:Header>
  <soap:Body>
    <PlaceOrder xmlns="urn:example:orders"><sku>A-1</sku><qty>2</qty></PlaceOrder>
  </soap:Body>
</soap:Envelope>

A header with mustUnderstand="1" that the receiver cannot process must produce a MustUnderstand fault and no application processing.
Intermediate nodes can remove a header block once they have acted on it, which is how routing metadata is consumed by a gateway.
Headers are ordered and can repeat, so an application header with the same name twice is a schema decision, not an accident.
Never put business data in a header: consumers routinely drop the header when they republish the payload.

What the WS-* specifications add

Specification	Adds	Still used?
WS-Addressing	Transport-neutral destination, action and correlation identifiers	Frequently, especially with queues
WS-Security	Message-level signing, encryption and credentials	Frequently in regulated integrations
WS-ReliableMessaging	Guaranteed ordered delivery over unreliable transports	Rarely; message queues are usually simpler
WS-Policy	Machine-readable statement of required headers and security	When WS-Security is used
WS-Trust	Token issuing and exchange for federated identity	In older enterprise SSO stacks
WS-AtomicTransaction	Distributed transactions across services	Very rarely; avoid
MTOM / XOP	Efficient binary attachment encoding	Yes, for large payloads

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
            xmlns:sp="http://docs.oasis-open.org/ws-sx/ws-securitypolicy/200702">
  <wsp:ExactlyOne>
    <wsp:All>
      <sp:TransportBinding>
        <wsp:Policy>
          <sp:TransportToken>
            <wsp:Policy><sp:HttpsToken RequireClientCertificate="false"/></wsp:Policy>
          </sp:TransportToken>
          <sp:AlgorithmSuite><wsp:Policy><sp:Basic256/></wsp:Policy></sp:AlgorithmSuite>
        </wsp:Policy>
      </sp:TransportBinding>
    </wsp:All>
  </wsp:ExactlyOne>
</wsp:Policy>

⚠️

Adding a mustUnderstand header is a breaking change for every consumer that does not know it. When a client cannot satisfy the requirement it receives a fault and the request is never processed, so rollout order is client first, then service.

FAQ

Do I need WS-Addressing if I use plain HTTP?

Not for routing, but the correlation and action identifiers are useful for tracing and for asynchronously delivered responses. Many platforms add the headers by default.

What replaces WS-ReliableMessaging today?

A durable queue between the hops. Broker-level guarantees are simpler to operate and easier to reason about than a per-message acknowledgement protocol.

WS-Security: authentication, signing and encryption What SOAP is and how the envelope works

Last refreshed 2026-09-18.

SOAP headers and the WS-* standards

Header blocks and mustUnderstand

What the WS-* specifications add

FAQ

Related