AS2 Gateway Real-time Notification Webhooks

Webhooks for "Received MDN" Events

When AS2 Gateway receives an MDN receipt for a message you have sent out (to one of your partners from one of your stations), it will send a HTTP POST request to the MDN webhook URL that you have configured, along with the metadata of that MDN.

The webhook is invoked for both synchronous (returned on the same HTTP channel that sends out the message) and asynchronous (sent back later by the partner as a new HTTP request) MDNs.

Extracting Metadata from HTTP Request Headers

Content of the request would vary, based on the selected payload mode/format. Yet, all requests would contain the following HTTP headers for quick access to the whereabouts of the message:

  • AS2-From: AS2 identifer of the MDN sender (remote trading partner)

  • AS2-To: AS2 identifer of the MDN receiver (your trading station)

  • Message-ID: AS2 identifier of the MDN

  • Original-Message-ID: AS2 identifier of the original (sent) message corresponding to this MDN

  • Received-Content-MIC: Content-MIC value extracted from the MDN

  • Subject: subject line of the MDN

  • X-Partner-Type: type of the trading partner as configured on AS2 Gateway; "Test" or "Production"

Additional HTTP/AS2 headers may also be present, which can safely be ignored.

Original AS2/HTTP headers received in the MDN are passed through to the webhook, verbatim; character case (upper/lower), whitespaces etc. of header keys may differ based on the sender’s AS2 system.
Original-Message-ID and Received-Content-MIC are not standard AS2/HTTP headers; they are extracted from the MDN content and included into the webhook’s HTTP headers, for your convenience.

If the MDN contains an error, an additional X-Processing-Error header will be added; containing the error data, in this format:

errorCode1: error message 1: description 1; errorCode2: error message 2: description 2; ...

E.g.:

X-Processing-Error: 300: Invalid content for async MDN: Generic error; 400: Unexpected processing error: Generic error

Headers-only (default)

Only the headers are available; payload will be empty.

As outlined before, almost all the important pieces of data are available as individual tokens in the header values, and can be extracted out straightaway (in a request.getHeader("name") fashion) without having to do any additional parsing.

POST /webhook/mdn HTTP/1.1
mime-version: 1.0
date: Mon, 22 Jun 2020 12:29:34 IST
server: acme.server
Received-Content-MIC: BdwvEtnDb5zfkORKm6fK/hZNxhinbjFUdp7ZpgzcYVI=, sha-256
as2-version: 1.2
subject: Message Delivery Notification
recipient-address: http://service.as2gateway.com:8280/service/as2-async-mdn-receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592809174111-6@_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@acme.hostname
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha1;  boundary="----=_Part_33_188931338.1592809174127"
Original-Message-ID: <1647581489.0.1592807247716@as2gateway.com>
X-Partner-Type: Production
Content-Length: 0
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraStudio UltraESB-X
Accept-Encoding: gzip

JSON Metadata

In addition to headers, the request contains a JSON payload representing the received MDN, resembling an MDN entity from the V1 API.

POST /webhook/mdn HTTP/1.1
mime-version: 1.0
date: Mon, 22 Jun 2020 12:29:34 IST
server: acme.server
Received-Content-MIC: BdwvEtnDb5zfkORKm6fK/hZNxhinbjFUdp7ZpgzcYVI=, sha-256
as2-version: 1.2
subject: Message Delivery Notification
recipient-address: http://service.as2gateway.com:8280/service/as2-async-mdn-receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592809174111-6@_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@acme.hostname
Content-Type: application/json
Original-Message-ID: <1647581489.0.1592807247716@as2gateway.com>
X-Partner-Type: Production
Content-Length: 65
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraStudio UltraESB-X
Accept-Encoding: gzip

{"content":"The AS2 message has been received.","mdnError":false}

Raw Payload

In addition to headers, the raw MIME content of the received MDN is posted in the payload. This is a MIME multipart (as per the AS2 specification) and can be parsed using the boundary from the Content-Type header.

POST /webhook/mdn HTTP/1.1
mime-version: 1.0
date: Mon, 22 Jun 2020 12:29:34 IST
server: acme.server
Received-Content-MIC: BdwvEtnDb5zfkORKm6fK/hZNxhinbjFUdp7ZpgzcYVI=, sha-256
as2-version: 1.2
subject: Message Delivery Notification
recipient-address: http://service.as2gateway.com:8280/service/as2-async-mdn-receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592809174111-6@_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@acme.hostname
Content-Type: multipart/signed; protocol="application/pkcs7-signature"; micalg=sha1;  boundary="----=_Part_33_188931338.1592809174127"
Original-Message-ID: <1647581489.0.1592807247716@as2gateway.com>
X-Partner-Type: Production
Content-Length: 65
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraStudio UltraESB-X
Accept-Encoding: gzip

------=_Part_33_188931338.1592809174127
Content-Type: multipart/report; report-type=disposition-notification;
	boundary="----=_Part_8_1487173726.1576500399649"

------=_Part_8_1487173726.1576500399649
Content-Type: text/plain
Content-Transfer-Encoding: 7bit

MDN for Message-ID: <1647581489.0.1592807247716@as2gateway.com>
...
In this topic
In this topic