Header
OptionalSOAP 1.1: Optional. mustUnderstand="1" or "0"
SOAP 1.2: Optional. mustUnderstand="true" or "false"
The Header contains optional metadata blocks: authentication tokens, routing instructions (WS-Addressing), transaction IDs, and tracing context. Each header block can carry mustUnderstand='1' (SOAP 1.1) or mustUnderstand='true' (SOAP 1.2) to mandate that the receiver processes it or returns a MustUnderstand fault.
Details
The Header is the SOAP extension mechanism. It carries cross-cutting concerns that are separate from the business payload in the Body.
Common header contents: WS-Security: username/password, X.509 certificates, SAML assertions, digital signatures WS-Addressing: To, From, ReplyTo, MessageID, Action for routing and correlation Transaction ID: for distributed tracing Custom auth headers: API keys, session tokens
mustUnderstand attribute: SOAP 1.1: mustUnderstand="1" means the receiving node MUST understand and process this header block. If it cannot, it MUST return a SOAP Fault with faultcode = MustUnderstand. SOAP 1.2: mustUnderstand="true" – same semantics. mustUnderstand="0" / "false" – receiver may ignore the header if it doesn't understand it.
role/actor attribute: SOAP 1.1 uses actor (a URI identifying the intended recipient) SOAP 1.2 uses role (same concept, standardized roles: next, ultimateReceiver, none) In a SOAP intermediary chain, a header block marked for an intermediary role is processed and removed by that intermediary before forwarding.
The Header MUST appear before Body if present.
Attributes
| Attribute | Description |
|---|---|
| mustUnderstand | 1/true: receiver MUST process or fault. 0/false: receiver may ignore if not understood. |
| actor (1.1) | URI of the intended recipient node in a processing chain. |
| role (1.2) | Standardized: next, ultimateReceiver, none. Replaces SOAP 1.1 actor. |
| relay (1.2) | If true, relay this block unchanged if the role does not match. SOAP 1.2 only. |
Examples
<soap:Header>
<wsse:Security
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
soap:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>alice</wsse:Username>
<wsse:Password
Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">
hashedpassword==
</wsse:Password>
<wsse:Nonce>abc123==</wsse:Nonce>
<wsu:Created>2026-07-24T10:00:00Z</wsu:Created>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header><soap:Header>
<wsa:To xmlns:wsa="http://www.w3.org/2005/08/addressing">
http://service.example.com/process
</wsa:To>
<wsa:Action>http://example.com/CustomerService/GetCustomer</wsa:Action>
<wsa:MessageID>urn:uuid:6B29FC40-CA47-1067-B31D-00DD010662DA</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>http://client.example.com/callback</wsa:Address>
</wsa:ReplyTo>
</soap:Header>