SOAP Message Structure — Envelope, Header, Body, and Fault Elements

In this tutorial, you will learn about SOAP Message Structure. We cover key concepts, practical examples, and best practices to help you master this topic.

A SOAP message is an XML document with a standard structure consisting of an Envelope (root), an optional Header for metadata, a required Body containing the actual message, and an optional Fault for error information.

What You'll Learn

• The four main elements of a SOAP message
• How to construct SOAP request and response messages
• How SOAP Faults communicate errors

Why It Matters

SOAP's strict message structure ensures interoperability across platforms. Any SOAP-compliant client can communicate with any SOAP-compliant server because the message format is standardized. Understanding this structure is essential for debugging SOAP integrations.

Real-World Use

DodaTech's enterprise threat intelligence integration uses SOAP messages. The Envelope wraps the entire message, the Header carries WS-Security credentials, the Body contains the threat query, and Fault elements report validation errors.

Message Structure

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ns="http://dodatech.com/threat-intel">

  <soap:Header>
    <ns:Authentication>
      <ns:ApiKey>your-api-key</ns:ApiKey>
      <ns:Timestamp>2026-06-28T10:30:00Z</ns:Timestamp>
    </ns:Authentication>
  </soap:Header>

  <soap:Body>
    <ns:QueryThreatIntel>
      <ns:ThreatId>THR-2026-4719</ns:ThreatId>
      <ns:IncludeIndicators>true</ns:IncludeIndicators>
    </ns:QueryThreatIntel>
  </soap:Body>

</soap:Envelope>

SOAP Fault Structure

import xml.etree.ElementTree as ET

def parse_soap_fault(response_xml):
    """Parse a SOAP Fault response"""
    root = ET.fromstring(response_xml)
    ns = {'soap': 'http://schemas.xmlsoap.org/soap/envelope/'}

    fault = root.find('.//soap:Fault', ns)
    if fault is not None:
        faultcode = fault.find('soap:faultcode', ns).text if fault.find('soap:faultcode', ns) is not None else None
        faultstring = fault.find('soap:faultstring', ns).text if fault.find('soap:faultstring', ns) is not None else None
        detail = fault.find('soap:detail', ns)

        return {
            'code': faultcode,
            'message': faultstring,
            'detail': ET.tostring(detail, encoding='unicode') if detail is not None else None
        }
    return None

Complete SOAP Request

import requests

def send_soap_request(endpoint, soap_action, body_xml, headers_xml=None):
    """Send a SOAP request and parse the response"""
    soap_envelope = f'''<?xml version="1.0" encoding="UTF-8"?>
    <soap:Envelope
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:ns="http://dodatech.com/threat-intel">
        {headers_xml or ''}
        <soap:Body>
            {body_xml}
        </soap:Body>
    </soap:Envelope>'''

    headers = {
        'Content-Type': 'text/xml; charset=utf-8',
        'SOAPAction': soap_action
    }

    response = requests.post(endpoint, data=soap_envelope, headers=headers)

    if response.status_code == 200:
        return parse_soap_response(response.text)
    else:
        fault = parse_soap_fault(response.text)
        return {'error': fault}

def parse_soap_response(xml_str):
    """Extract the Body content from a SOAP response"""
    root = ET.fromstring(xml_str)
    ns = {'soap': 'http://schemas.xmlsoap.org/soap/envelope/'}
    body = root.find('.//soap:Body', ns)
    return ET.tostring(body, encoding='unicode')

Common Mistakes

1. Missing SOAP Envelope Namespace

The Envelope must include the correct namespace. Missing or incorrect namespace causes the SOAP processor to reject the message.

2. Not Setting SOAPAction Header

Some SOAP implementations require the SOAPAction HTTP header. Without it, the server may not route the request correctly.

3. Incorrect XML Encoding

SOAP messages must be UTF-8 encoded. Special characters in the body must be XML-escaped.

4. Mixing SOAP Versions

SOAP 1.1 and 1.2 have different namespace URIs and Fault structures. Ensure client and server use the same version.

5. Omitting the Fault Handler

Always parse the Fault element. A non-200 response likely contains a Fault with details about what went wrong.

Practice Questions

1. What are the four main elements of a SOAP message?
2. What namespace does SOAP 1.1 use?
3. What is the SOAPAction header used for?
4. What elements does a SOAP Fault contain?
5. How do you handle SOAP errors?

Answers

1. Envelope, Header (optional), Body (required), Fault (optional). 2. http://schemas.xmlsoap.org/soap/envelope/. 3. It identifies the intended SOAP action/operation. 4. faultcode, faultstring, faultactor (optional), detail (optional). 5. Check for a Fault element in the response body.

Challenge

Build a SOAP message Builder that constructs valid Envelope, Header, Body, and Fault elements, supports both SOAP 1.1 and 1.2 namespaces, and validates the message structure before sending.

FAQ

Mini Project

Build a SOAP client library that: constructs valid SOAP messages with proper namespaces, supports Header injection, parses responses and Faults, handles both SOAP versions, and provides typed methods for common operations.

What's Next

• Learn about the SOAP Envelope namespace in detail
• Explore SOAP Header elements for WS-Addressing and WS-Security
• Continue to WSDL structure for service description