Webhook Integration for AS2 & SFTP

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. Webhooks 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. 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.

Deprecation Notice and Change Summary: 3.1.1
In order to be compatible with multiple message services, MFT Gateway has made some changes to the existing message-related Webhook JSON payloads. Please click here for more details

1.2 Enabling / Disabling Webhooks

You can visit ‘Webhooks’ from the Integrations menu icon on the left navigation menu and will be presented with the above page. Here, there are two separate tabs for configuring AS2 and SFTP webhooks, where one or more webhook endpoints can be specified for each service type.

MFT Gateway’s webhook invocations currently do not follow redirects (HTTP 301, 302, 307 etc.).

2 Webhook Integration for AS2

Under webhook configuration for AS2, you can configure each webhook endpoint against one Station, or a one endpoint for all Stations. You cannot provide two webhook endpoints for the same Station. To disable any webhook, simply 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 every Station, use the ‘All Stations’ webhook type.

2.1 Webhook AS2 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.

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

2.2 Received Message

Triggered when a new message has been received. The 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"
}

2.3 Sent Message

Triggered when a submitted message has been successfully delivered. The 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.2 for an explanation of the key attributes.

2.4 Send Failure

Triggered when a submitted message has failed delivery and has exhausted the automatic retries. The 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 sent message payload under Section 2.3, the Send Failure JSON payload would also include:

2.5 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.2 for an explanation of the key attributes.

3 Webhook Integration for SFTP

Under webhook configuration for SFTP, you can configure each webhook endpoint against one Partner, or a one endpoint for all Partners. You cannot provide two webhook endpoints for the same Partner. To disable any webhook, simply remove it from the list by clicking the delete icon.

By configuring a webhook endpoint against only one Partner, only events specific to that partner will be filtered and sent to the endpoint. To catch all events for every Partner, use the ‘All Partners’ webhook type.

3.1 Webhook SFTP Message formats

3.2 Received Message

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

{
  "service": "sftp",
  "to": "sample+1@email.com",
  "messageId": 1326339681164104,
  "messageIdentifier": "<1326339681164104.sftp@mftgateway.com>",
  "timestamp": 1710470763364,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "attachments": [
    "SFTP/partners/mypartnerid/inbox/1326339681164104/33below100kb.txt"
  ],
  "tenantId": 1281544151911037,
  "bucketName": "Bucket name",
  "tenantName": "Tenant name",
  "tenantEmail": "sample+1@email.com",
  "eventType": "MESSAGE.RECEIVED.SUCCESS",
  "receivedAt": 1710470763364
}

3.3 Sent Message

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

{
  "service": "sftp",
  "to": "sample+1@email.com",
  "messageId": 1326344589580675,
  "messageIdentifier": "<1326344589580675.sftp@mftgateway.com>",
  "timestamp": 1710471258940,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "attachments": [
    "SFTP/partners/mypartnerid/outbox/1326344589580675/33below100kb.txt"
  ],
  "tenantId": 1281544151911037,
  "bucketName": "Bucket name",
  "tenantName": "Tenant Name",
  "tenantEmail": "sample+1@email.com",
  "eventType": "MESSAGE.SEND.SUCCESS",
  "sentAt": 1710471258940
}

3.4 Send Failure

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

{
  "service": "sftp",
  "to": "sample+1@email.com",
  "messageId": 1326344589580675,
  "messageIdentifier": "<1326344589580675.sftp@mftgateway.com>",
  "timestamp": 1710471258940,
  "partnerIdentifier": "mypartnerid",
  "partnerName": "Partner Name",
  "attachments": [
    "SFTP/partners/mypartnerid/outbox/1326344589580675/33below100kb.txt"
  ],
  "failureReason": "Cannot resolve partner hostname",
  "failures": 1,
  "lastAttemptTime": 1665036942928,
  "tenantId": 1281544151911037,
  "bucketName": "Bucket name",
  "tenantName": "Tenant Name",
  "tenantEmail": "sample+1@email.com",
  "eventType": "MESSAGE.SEND.FAILURE",
  "sentAt": 1710471258940
}

4 Webhook Configuration

4.1 Webhook Retry

To increase the reliability of Webhook notifications, you can enable Webhook Retry. When the Retry is enabled, MFTG will attempt to resend failed webhook requests in the configured intervals.

Anytime a webhook endpoint response does not return a 2xx success response, MFTG will retry the request.

You can configure how many times a failed webhook should retry, and the initial retry delay. For example, consider the following Webhook retry setup.

Initial Retry Delay: 2 min

Number of Retries Before Give Up: 5 times

In the above case, after the initial failure response, MFTG will wait 2 minutes to retry and then double the time between retries each time. After the first retry, the webhook requests will retry in 4 min, 8 min, 16 min, and 32-minute intervals.

The following table demonstrates the retry intervals for each initial retry delay when the Number of Retries Before giving up is 5.

The configurable number of retries are 3, 5, or 10 and each will follow the retry pattern in the above table.

If MFTG receives a 2xx response for any of the retries, the Webhook Retry process will be stopped immediately.

MFTG time-out for webhook requests is 30 seconds. If the webhook endpoint does not respond before the time-out when the Webhook Retry is enabled, those requests will be considered as failures and will also be retried in configured intervals.

4.2 Signature for Webhook Payload

When this feature is enabled, MFT Gateway will calculate the SHA-256 (pkcs1-sha256) signature for the webhook payload using a system-generated key pair (dedicated to your account) and include the calculated signature in request headers as a custom HTTP header.

Webhook signature custom HTTP header name: mftg-wh-signature

You can verify the received signature using the webhook public certificate. Public Certificate can be downloaded from the UI (01)

If required, you can convert the downloaded public certificate to public key format using the following OpenSSL command:

openssl x509 -pubkey -noout -in webhook-cert.pem > webhook-pubkey.pem

Signature Verification:

For JavaScript, you can directly use the JSON Sign NPM module to verify the signature.

4.3 Add Custom Header

You can Add any valid custom header for your Webhook request by enabling this option. This header will be included in every webhook request, including webhook retries.

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

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

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