Skip to main content
phase4 receives AS4 messages over HTTP using a standard Jakarta Servlet. Incoming requests are parsed, validated, decrypted, and verified before being handed off to your application code via the Java Service Provider Interface (SPI) mechanism.

​
Architecture

The receiving stack consists of four layers:
1

HTTP request arrives at the servlet

An HTTP POST request carrying an AS4 message reaches the registered servlet endpoint (typically /as4).
2

AS4XServletHandler dispatches the request

AS4XServletHandler reads the request stream, creates AS4IncomingMessageMetadata capturing connection metadata, and delegates to AS4RequestHandler.
3

AS4RequestHandler parses and validates

The handler parses the SOAP envelope, verifies the WS-Security signature, decrypts the payload, checks the AS4 profile constraints, detects duplicates, and builds the response (receipt or error signal).
4

SPI processors receive the clean payload

All registered IAS4IncomingMessageProcessorSPI implementations are called with the decrypted, verified payload. Your application logic lives here.
HTTP POST /as4
     │
     ▼
AS4Servlet (or Phase4PeppolAS4Servlet)
     │  registers handler for HTTP POST
     ▼
AS4XServletHandler
     │  creates AS4IncomingMessageMetadata
     │  optionally calls IAS4ServletRequestHandlerCustomizer.customizeBeforeHandling()
     ▼
AS4RequestHandler.handleRequest()
     │  parses SOAP / MIME multipart
     │  verifies signature (WSS4J)
     │  decrypts payload
     │  validates against AS4 profile
     │  checks for duplicates
     ▼
IAS4IncomingMessageProcessorSPI (one or more, loaded via ServiceLoader)
     │  processAS4UserMessage()   – user messages
     │  processAS4SignalMessage() – receipts / errors / pull-requests
     ▼
Receipt or Error signal returned to sender

​
Key classes

Class / InterfaceRole
AS4ServletThin Jakarta Servlet that wires AS4XServletHandler for HTTP POST
Phase4PeppolAS4ServletPeppol-specific servlet that configures the security customizer automatically
AS4XServletHandlerMain servlet handler; creates metadata and runs AS4RequestHandler
IAS4ServletRequestHandlerCustomizerOptional hook to configure AS4RequestHandler before/after processing
AS4RequestHandlerCore pipeline: parse → verify → decrypt → profile-check → SPI dispatch
IAS4IncomingMessageProcessorSPISPI interface your application implements to receive user/signal messages
AS4IncomingMessageMetadataTransport-level metadata (IP, TLS cert, timestamp) for one incoming request
AS4ServerInitializerOne-time server bootstrap: registers managers and schedules duplicate cleanup

​
The SPI pattern

phase4 uses java.util.ServiceLoader to discover all IAS4IncomingMessageProcessorSPI implementations on the classpath. To register your implementation, create the file: 
META-INF/services/com.helger.phase4.incoming.spi.IAS4IncomingMessageProcessorSPI
and list your fully-qualified class name inside it. Multiple implementations are supported and all are called for each message.
For Peppol networks, phase4 ships Phase4PeppolServletMessageProcessorSPI which already implements this SPI. It unwraps the SBDH payload and delegates to your IPhase4PeppolIncomingSBDHandlerSPI. You only need to implement the latter.

​
Next steps

Servlet setup

Register AS4Servlet in web.xml and configure AS4XServletHandler.

Peppol server

Use Phase4PeppolAS4Servlet and implement IPhase4PeppolIncomingSBDHandlerSPI.

Message processing

Understand the processing lifecycle, metadata, duplicate detection, and error handling.

Build docs developers (and LLMs) love

Get started for freeTalk to us