AS2 Gateway Real-time Notification Webhooks

Webhooks for "Received Message" Events

When AS2 Gateway receives a new AS2 message on your behalf (to one of your stations, from one of your partners), it will send a HTTP POST request to the message webhook URL that you have configured - usually within a few seconds - containing the metadata of that message.

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 sender (remote trading partner)

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

  • Message-ID: AS2 identifier of the received message

  • Subject: subject line of the received message

  • 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 headers received in the AS2 message 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.

If there was an error processing the AS2 message, an additional X-Processing-Error header will be added; containing the error data, in this format:

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

E.g.:

X-Processing-Error: 800: Decryption failure: bad certificate; 1100: Parse failed

In such cases, the raw payload mode may not contain any data (i.e. an empty request body).

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/message HTTP/1.1
mime-version: 1.0
date: Mon, 15 Jun 2020 13:48:56 IST
as2-version: 1.2
subject: Invoice #981712
recipient-address: http://service.as2gateway.com:8280/service/as2-receiver
receipt-delivery-option: http://acme.hostname:8085/as2/receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592209136307-2@ACME_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@acme.hostname
Content-Type: application/pkcs7-mime; name="smime.p7m"; smime-type=enveloped-data
disposition-notification-to: http://acme.hostname:8085/as2/receiver
disposition-notification-options: signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256
X-Partner-Type: Production
Content-Length: 0
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraESB-X
Accept-Encoding: gzip

JSON Metadata

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

POST /webhook/message HTTP/1.1
mime-version: 1.0
date: Mon, 15 Jun 2020 13:48:56 IST
as2-version: 1.2
subject: Invoice #981712
recipient-address: http://service.as2gateway.com:8280/service/as2-receiver
receipt-delivery-option: http://acme.hostname:8085/as2/receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592209136307-2@ACME_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@acme.hostname
Content-Type: application/json
disposition-notification-to: http://acme.hostname:8085/as2/receiver
disposition-notification-options: signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256
X-Partner-Type: Production
Content-Length: 255
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraESB-X
Accept-Encoding: gzip

{"as2MessageId":"<AS2-1592209136307-2@ACME_MY-OWN-ORG>","compressed":false,"encrypted":true,"signed":true,"subject":"Invoice #981712","receiverId":"MY-OWN-ORG","senderId":"ACME","partnerType":"Production","attachments":[{"name":"981712.xml","size":3570}]}

Raw Payload

In addition to headers, the attachment received within the AS2 message is posted in the payload, along with appropriate Content-Disposition (original file name) and Content-Type headers.

POST /webhook/message HTTP/1.1
mime-version: 1.0
date: Mon, 15 Jun 2020 13:48:56 IST
as2-version: 1.2
subject: Invoice #981712
recipient-address: http://service.as2gateway.com:8280/service/as2-receiver
receipt-delivery-option: http://acme.hostname:8085/as2/receiver
ediint-features: multiple-attachments, CEM
as2-from: ACME
message-id: <AS2-1592209136307-2@ACME_MY-OWN-ORG>
X-Forwarded-For: 52.204.119.191
as2-to: MY-OWN-ORG
from: sender@ACME.com
disposition-notification-to: http://acme.hostname:8085/as2/receiver
disposition-notification-options: signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha-256
X-Partner-Type: Production
Content-Length: 3570
Host: webhook.myown.org
Connection: Keep-Alive
User-Agent: AdroitLogic UltraESB-X
Accept-Encoding: gzip
Content-Disposition: attachment; filename=981712.xml
Content-Type: text/xml

<?xml version="1.0" encoding="UTF-8"?>
<invoice>
<header>
...
If the message contained multiple files, only the first one is posted in the request. In such cases, an additional X-Truncated: Attachments: 1/n header is included to indicate the total number (n) of available attachments.
In this topic
In this topic