free web stats
Link Search Menu Expand Document

Webhook Integration for AS2

1 Introduction

The MFTGateway allows integration based on webhooks, to notify you of incoming messages or other similar events. Webhooks works well with the REST APIs, or even SFTP or S3 based integration, and avoids the need for polling. This requires the assignment of one or more external Webhook endpoints, exposed over an HTTP or HTTPS URL. Wehbooks allow you to trigger custom actions or alerts based on events.

Webhook notifications use best-effort delivery without any guarantees. If your webhook endpoint was unavailable, or encountered a network error or timeout etc, the notification may become lost, and will not be replayed. As with any distributed system, the use of a polling mechanism to rectify and reconcile any such lost events would be preferable.

1.1 Implementing a webhook

A webhook is a simple HTTP endpoint that can handle POST requests, sent by the MFT Gateway. We recommend a SLAppForge Sigma based Lambda function for the best experience in implementing a quick but powerful webhook for Amazon AWS or Google GCP cloud environments.

Deprecation notice and Change Summary : 3.1.1

Changes to how Stations are identified:

stationAS2ID attribute used to identify Station AS2 ID will be removed and stationIdentifier will be used instead.

Webhook notification currently sends both stationAS2ID and stationIdentifier, but after the deprecation period ends, only the stationIdentifier will be sent.

Changes to how Partners are identified:

partnerAS2ID attribute used to identify Partner AS2 ID will be removed and partnerIdentifier will be used instead.

Webhook notification currently sends both partnerAS2ID and partnerIdentifier , but after the deprecation period ends, only the partnerIdentifier will be sent.

Changes to how AS2 Message IDs are identified:

messageAS2ID attribute used to identify AS2 Message ID will be removed and messageIdentifier will be used instead.

Webhook notification currently sends both messageAS2ID and messageIdentifier,but after the deprecation period ends, only the messageIdentifier will be sent.

New key attributes introduced in version 3.1.1

Old key attributeNew key attribute
messageAS2IDmessageIdentifier
partnerAS2IDpartnerIdentifier
stationAS2IDstationIdentifier
-service
-messageId

The deprecation period for these changes began on 12 October 2022.

By 01 January 2023, we will remove old attributes, such as partnerAS2ID and stationAS2ID, and instead will only use the new attributes (partnerIdentifier, stationIdentifier).

2 Webhook Message formats

An incoming webhook message includes an eventType attribute, which will help differentiate between the possible types of messages. See below sections on sample message contents.

Webhook eventWebhook eventType
Send a message from MFT GatewayMESSAGE.SEND.SUCCESS
Receive message to MFT GatewayMESSAGE.RECEIVED.SUCCESS
Message send failureMESSAGE.SEND.FAILED
Incomplete outgoing messageMESSAGE.SEND.INCOMPLETE

All 4 scenarios will send a JSON payload with the message details.

2.1 Received Message

Triggered when a new message has been received. Request contains a JSON payload representing the received entity (AS2 message) such as the following.

{
  "service": "as2",
  "to": "sample+1@email.com",
  "messageId": 871999751123456,
  "messageIdentifier": "<467855488300248@mftgateway.com>",
  "messageSubject": "Test Receive message",
  "timestamp": 1665036775506,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "stationIdentifier": "mystationid",
  "stationName": "Station Name",
  "Attachments":[
    "AS2/files/mystationid/mypartnerid/inbox/1616042383-195/sample.json",
    "AS2/files/mystationid/mypartnerid/inbox/1616042383-195/testfile.txt"
  ],
  "bucketName": "mftg-bucketname.test.mftgateway.com",
  "tenantName": "abc.test.mftgateway.com",
  "tenantId": 301713382762123,
  "tenantEmail": "tenant@email.com",
  "messageAS2ID": "<467855488300248@mftgateway.com>",  //Deprecated
  "partnerAS2ID": "mypartnerid",  //Deprecated
  "stationAS2ID": "mystationid",  //Deprecated
  "receivedAt": 1665036775506,
  "eventType": "MESSAGE.RECEIVED.SUCCESS"
}
partnerAS2IDAS2 identifier of the sender (remote trading partner)
stationAS2IDAS2 identifier of the receiver (your trading station)
messageAS2IDAS2 identifier of the received message
messageSubjectsubject line of the received message
attachmentsS3 / SFTP path of the received attachment / s
bucketNameName of the S3 bucket where all the attachments will be saved.

2.2 Sent Message

Triggered when a submitted message has been successfully delivered. Request contains a JSON payload representing the sent entity (AS2 message) such as the following.

{
  "service": "as2",
  "to": "sample+1@email.com",
  "messageId": 871999751123456,
  "messageIdentifier": "<467855488300248@mftgateway.com>", 
  "messageSubject": "Test Sent message",
  "timestamp": 1665036775506,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "stationIdentifier": "mystationid",
  "stationName": "Station Name",
  "attachments": [
"AS2/files/mystationid/mypartnerid/outbox/1616042383-195/sample.json",
"AS2/files/mystationid/mypartnerid/outbox/1616042383-195/testfile.txt"
  ],
  "bucketName": "mftg-bucketname.test.mftgateway.com",
  "tenantName": "abc.test.mftgateway.com",
  "tenantId": 301713382762123,
  "tenantEmail": "tenant@email.com",
  "messageAS2ID": "<467855488300248@mftgateway.com>",  //Deprecated
  "partnerAS2ID": "mypartnerid",  //Deprecated
  "stationAS2ID": "mystationid",  //Deprecated
  "sentAt": 1665036775506,
  "eventType": "MESSAGE.SEND.SUCCESS"
}

See Section 2.1 for an explanation of the key attributes.

2.3 Send Failure

Triggered when a submitted message has failed delivery and has exhausted the automatic retries. Request contains a JSON payload representing the failed entity (AS2 message) such as the following.

{
  "service": "as2",
  "to": "sample+1@email.com",
  "messageId": 872001422112345,
  "messageIdentifier": "<467855488312345@mftgateway.com>",
  "messageSubject": "Test Fail message",
  "timestamp": 1665036942587,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "stationIdentifier": "mystationid",
  "stationName": "Station Name",
  "attachments": [
"AS2/files/mystationid/mypartnerid/outbox/1616042383-195/sample.json",
"AS2/files/mystationid/mypartnerid/outbox/1616042383-195/testfile.txt"
  ],
  "failureReason": "Cannot resolve partner hostname",
  "failures": 1,
  "lastAttemptTime": 1665036942928,
  "bucketName": "mftg-bucketname.test.mftgateway.com",
  "tenantName": "abc.test.mftgateway.com",
  "tenantId": 301713382761234,
  "tenantEmail": "tenant@email.com",
  "messageAS2ID": "<467855488312345@mftgateway.com>",  //Deprecated
  "partnerAS2ID": "mypartnerid",  //Deprecated
  "stationAS2ID": "mystationid",  //Deprecated
  "sentAt": 1665036942587,
  "eventType": "MESSAGE.SEND.FAILED"
}

In addition to the details in the received message payload under Section 2.1, send failure JSON payload would also include:

failureReasonReason for the message send failure
failuresHow many times the message has failed
lastAttemptTimeWhen is the last send attempt

2.4 Incomplete Outgoing message

Triggered when a submitted message has changed the status to incomplete and has exhausted the automatic retries. MFT Gateway marks outgoing messages as Incomplete when the trading partner accepted the message but failed to acknowledge back within the maximum waiting time. Webhook request contains a JSON payload representing the incompleted entity (AS2 message) such as the following.

{
  "service": "as2",
  "to": "sample+1@email.com",
  "messageId": 876512739112345,
  "messageIdentifier": "<467855488300248@mftgateway.com>",
  "messageSubject": "Test Incomplete message",
  "timestamp": 1665488074723,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "stationIdentifier": "mystationid",
  "stationName": "Station Name",
  "attachments": [
    "AS2/files/mystationid/mypartnerid/outbox/1616042383-195/sample.json"
  ],
  "bucketName": "mftg-bucketname.test.mftgateway.com",
  "tenantName": "abc.test.mftgateway.com",
  "tenantId": 16004015842812345,
  "tenantEmail": "tenant@email.com",
  "messageAS2ID": "<467855488300248@mftgateway.com>", //Deprecated
  "partnerAS2ID": "mypartnerid", //Deprecated
  "stationAS2ID": "mystationid", //Deprecated
  "sentAt": 1665488074723,
  "eventType": "MESSAGE.SEND.INCOMPLETE"
}

See Section 2.1 for an explanation of the key attributes.

3 Webhook Configuration

3.1 Enabling / Disabling Webhooks

Webhook Integration

You can visit ‘Webhooks’ from Integrations menu icon on the left navigation menu, and will be presented with the above page. Here, one or more webhook endpoints can be specified. Each webhook endpoint can be configured against one Station, or for all Stations. You cannot provide two webhook endpoints for the same Station. To disable any webhook, simple remove it from the list by clicking the delete icon.

By configuring a webhook endpoint against only one Station, only events specific to that station will be filtered and sent to the endpoint. To catch all events for any Station, use the ‘All Stations’ webhook type.

MFT 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 MFT Gateway, it may need to be explicitly imported into the system. In such cases, please contact MFT Gateway team with a copy of the respective certificate.