Articles in this section

AS2 listener

  • Updated
Follow

The AS2 listener is the inbound side of AS2 in Etlworks. It exposes an HTTPS endpoint that trading partners POST signed-and-encrypted AS2 messages to; the listener decrypts the message, verifies the signature, returns an MDN, and triggers a flow with the decrypted payload. For the outbound side, see the AS2 connector.

When to use this listener

Use the AS2 listener whenever you need to receive an EDI payload over AS2 — the most common case is inbound X12 from a B2B partner. The end-to-end usage walkthrough is in Working with X12 → Receive X12 over AS2.

How AS2 receive works

  1. The trading partner POSTs a signed-and-encrypted AS2 payload to the listener URL.
  2. The listener decrypts the payload with your private key.
  3. The signature is verified using the partner's public certificate.
  4. The decrypted payload is handed to the flow that uses this listener as its source.
  5. The MDN (signed or unsigned, per configuration) is returned as the HTTP response. Asynchronous MDN requests from the partner are accepted but Etlworks does not currently dispatch the MDN asynchronously — see Working with X12 → AS2 send and receive for the current limitation.

Create an AS2 listener

  1. Open the Connections > Listeners window and click +.
  2. Search for AS2 in the gallery. The listener lives under the EDI, Web Services, and APIs groups.
  3. Select AS2 and fill in the parameters described below.
  4. Build a flow whose source is this listener — the source format will be the EDI format that matches the inbound payload (typically an X12 format).
  5. Schedule the flow with a continuous-execution schedule so the listener stays live.

Parameters

Common parameters

Field What to enter
URL Pattern (required) The path on the listener's HTTP endpoint. Final URL is {integrator-host}/rest/v1/httplistener/<URL Pattern>. Use a unique path per partner, e.g., /as2/inbound/partner-x. This is what you give the partner as their AS2 endpoint.
Method (required) Fixed at POST — AS2 is HTTP POST-only.
Auth Type (required) Default None. Optional application-level authentication. Most AS2 exchanges rely on TLS plus AS2 signing / encryption for security; an additional HTTP auth layer is rare.
Pass request headers to the flow as parameters Default true. Exposes inbound HTTP and AS2 headers (AS2-From, AS2-To, Message-ID, Disposition-Notification-To, etc.) to the flow as variables.

POST processing

Field What to enter
POST/PUT processing (required) Default Sync. Synchronous: the inbound flow runs and the MDN is returned on the same HTTP response. Asynchronous: the inbound payload is queued and the listener returns HTTP 200 immediately — useful when the inbound flow does heavy downstream loading and would exceed the partner's timeout.
Queue priority If global queuing is enabled and this listener is set to Async, this value sets the queue priority for inbound requests.

AS2 identifiers

Field What to enter
Local AS2 Identifier (required) Your AS2 ID. The listener expects this value in the inbound AS2-To header and uses it as the AS2-From on the MDN response.
Partner AS2 Identifier The partner's AS2 ID. When set, the listener validates the inbound AS2-From header against this value — mismatches are rejected. Leave blank to accept any sender.
Message ID Domain Optional domain used when Etlworks generates the MDN's Message-ID header.

Inbound security

Credentials for decrypting the inbound payload and verifying the partner's signature.

Field What to enter
Inbound Decryption Certificate Your local certificate — inline PEM, file path under {app.data}, or PKCS12 / JKS keystore reference.
Inbound Decryption Certificate Type PEM, PKCS12, JKS.
Inbound Decryption Certificate Password Password for a PKCS12 / JKS keystore.
Inbound Decryption Certificate Alias Alias when the keystore holds multiple entries.
Inbound Decryption Private Key Your local private key. Required when the decryption certificate is PEM.
Inbound Decryption Private Key Password Password for an encrypted PEM private key.
Partner Signing Certificate The partner's public certificate, used to verify their signature on the inbound payload.
Partner Signing Certificate Type PEM, PKCS12, JKS.
Partner Signing Certificate Password Password for a PKCS12 / JKS keystore.
Partner Signing Certificate Alias Alias when the keystore holds multiple entries.

MDN response

Controls the Message Disposition Notification returned to the partner.

Field What to enter
MDN Type (required) Default signed. Other option: unsigned. When the partner expects a signed MDN, supply MDN signing credentials below.
MDN Signature Algorithm Default SHA256withRSA. Other options: SHA1withRSA, SHA384withRSA, SHA512withRSA, MD5withRSA.
MDN Signing Certificate The certificate used to sign the MDN — typically your local signing cert (same as outbound AS2).
MDN Signing Certificate Type PEM, PKCS12, JKS.
MDN Signing Certificate Password Password for a PKCS12 / JKS keystore.
MDN Signing Certificate Alias Alias when the keystore holds multiple entries.
MDN Signing Private Key Required when the MDN signing certificate is PEM.
MDN Signing Private Key Password Password for an encrypted PEM private key.

Certificate handling

Certificates can be supplied three ways, same as the AS2 connector:

  • Inline PEM — paste the certificate / key text directly into the field.
  • File path — reference a file on the Etlworks server. The {app.data} token resolves to the app-data directory; {app.data}/certs/decryption.pem is a typical layout.
  • PKCS12 / JKS keystore — reference a keystore file or inline content, plus its password and (when the keystore holds multiple entries) the alias.

Sending AS2: the AS2 connector

This listener handles the inbound direction only. To send AS2 messages to a trading partner, use the AS2 connector.

Related articles