AS2 Gateway Real-time Notification Webhooks

Webhook Configuration

During the beta, you may not be able to configure webhooks via the web console; instead, directly contact AS2 Gateway Team with the necessary details in order to get your webhook configured.

A webhook configuration on AS2 Gateway may include all or a subset of the following fields:

Station and Partner

These fields can be used to filter (receive only a subset of) events based on the source (partner) and destination (station), or to direct or route receive events from different sources/destinations to different webhooks.

Configurations described in this section with the term "messages", are applicable for MDNs as well.

Multiple Webhooks

For example, you can set up one webhook to only receive events for messages sent by an ACME partner to a MY-OWN-ORG station. At the same time you can configure more webhooks to handle other station-partner combinations (ACMEMY-SECOND-ORG, AMZNMY-SECOND-ORG, etc.).

Semi-global Fallback Webhooks (Multi-station or Multi-partner)

If you leave one of the station or partner fields unspecified, the resulting webhook URL will receive all events that do not match other "more specific" webhook entries.

For example, a message webhook with station MY-OWN-ORG and partner unspecified, will receive events for all messages received by MY-OWN-ORG from partners that are not already covered by other webhooks. That is, if you have the following webhooks:

ACME -> (unspecified)
ACME -> MY-OWN-ORG

an ACMEMY-OWN-ORG message will trigger the second webhook while ACMEMY-SECOND-ORG will trigger the first.

For consistency, your organization can have only one of each type of semi-global webhooks: one to cover unspecified stations, and another for unspecified partners.

The (Fully) Global Fallback Webhook (Multi-station, Multi-partner)

Your organization can have one global webhook (specifying neither a station nor a partner) that will handle all messages that do not match a "more specific" webhook.

Expanding on the previous semi-global example, an AMZNMY-OWN-ORG message will trigger the global webhook; as it would not match any other webhook entries.

Webhook URLs

URLs can be either HTTP or HTTPS. When invoked, they should return a HTTP 2xx (success-range) response, ideally with an empty body (payload), for the call to be considered successful.

AS2 Gateway’s webhook invocations currently do not follow redirects (HTTP 301, 302, 307 etc.).
If your HTTPS webhook endpoint has a TLS certificate that is not implicitly trusted by AS2 Gateway, it may need to be explicitly imported into the system. In such cases, please contact AS2 Gateway Team with a copy of the respective certificate.
If using the raw payload mode, your HTTP handler should be able to accept raw binary data (depending on the nature of the attachment types that your partner is expected to be sending).

Payload Formats or Modes

Depending on your use case, you can instruct AS2 Gateway to invoke your webhook using one of the following payload formats:

Headers-only (default)

Request contains a set of HTTP headers that include metadata fields representing the message: sender/partner (AS2-From), AS2-level message ID (Message-ID), etc. The payload (body) is empty.

JSON Metadata

Request contains the above headers, and also a JSON payload representing the received entity (AS2 message/MDN) - compatible with the V1 API data model.

Raw Payload

In addition to the previously-mentioned headers, data from the original event is directly posted in the payload:

  • for an AS2 message: the (first) attachment from the decoded content

  • for an MDN: the original, raw MIME payload of the MDN

Refer to the corresponding event documentation for more fine-grained details and examples on the webhook request content:

In this topic
In this topic