ballerinax/aayu.mftg.as2.trigger Ballerina library

0.9.0

Overview

The Aayu MFT Gateway AS2 Trigger module allows you to listen to the AS2 webhook events of Aayu MFT Gateway:

  • MESSAGE.RECEIVED.SUCCESS: an AS2 message was received from a trading partner
  • MESSAGE.SEND.SUCCESS: an AS2 message was sent to a trading partner
  • MESSAGE.SEND.FAILED: sending an AS2 message failed
  • MESSAGE.SEND.INCOMPLETE: an AS2 message was sent but its delivery was not confirmed

This module receives MFT Gateway's webhook deliveries directly - it does not call the MFT Gateway API on your behalf. It covers the AS2 events only; SFTP webhooks use different payloads.

Key features

  • Receives the four MFT Gateway AS2 events: message received, sent, send failed and send incomplete
  • Verifies every delivery with the webhook public key from MFT Gateway (RSA with SHA-256, mftg-wh-signature)
  • Typed payload records matching MFT Gateway's documented AS2 payloads
  • Acknowledges each delivery before running your handler, so a slow or failing handler doesn't cause retries
  • Services can be attached on their own path, so several triggers and HTTP services can share one port
  • Trigger services are listed by bal build --export-endpoints (Ballerina 2201.13.6 or later)

Setup guide

Before using this trigger in your Ballerina application, you need an MFT Gateway account with at least one AS2 station and trading partner, and a Ballerina service that MFT Gateway can reach over the internet to deliver webhook events to. The two sections below cover both a quick local test setup and a production deployment.

Try it out locally

Use this flow to test your event handling logic on your own machine before deploying anywhere, using ngrok to expose your local listener to the internet.

  1. Expose port 8090 with ngrok:

    Copy
    ngrok http 8090

    Copy the Forwarding URL ngrok prints out - this is your temporary public webhook URL.

    ngrok forwarding a public URL to localhost:8090
  2. In MFT Gateway, open Integrations > Webhooks from the left navigation menu and select the AS2 tab under General Configurations.

    MFT Gateway Webhook Integration page on the AS2 tab
  3. Click Add New Webhook and fill it in:

    • Station: the station you want events for, or All Stations.
    • Webhook URL: the ngrok forwarding URL from step 1.
    • Under Advanced Configurations, turn on Generate Signature For Webhook Payload. The listener rejects unsigned requests, so this is required.
    MFT Gateway webhook form with the ngrok URL and Generate Signature For Webhook Payload turned on
  4. Click Integrate Webhooks to save. A Webhook Public Key button then appears under the signature note; click it to download webhook-pubkey.pem. MFT Gateway signs each payload with a key pair dedicated to your account and sends the signature in the mftg-wh-signature header; the listener checks it with this public key.

    MFT Gateway signature note with the mftg-wh-signature header and the Webhook Public Key download button
  5. Put the whole public key, including the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- lines, in a Config.toml next to your service (see Quickstart below), and run it with bal run:

    Copy
    [<your_org>.<your_module_name>.userInput]
    webhookSecret = """-----BEGIN PUBLIC KEY-----
    MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...
    -----END PUBLIC KEY-----"""
  6. Send an AS2 message from Messages > Compose to one of your partners, or have a partner send one to your station. Each delivery shows up in the ngrok console with 200 OK, and your handler runs. To try it without a real trading partner, add a partner whose AS2 identifier, URL and certificate are your own station's (shown under View Partner Configuration on the station), and send to it: you get both a sent and a received event.

    ngrok console showing MFT Gateway webhook deliveries answered with 200 OK

Production / business integration

For production use, deploy your Ballerina service somewhere with a stable, internet-reachable HTTPS URL. Ballerina doesn't require any specific hosting platform - containers, a VM, a managed PaaS, or anything else that gives you a stable HTTPS endpoint all work equally well.

Keep the public key in Config.toml (or your platform's equivalent configuration/secret mechanism) as shown above, then set your production URL as the webhook URL in MFT Gateway.

If you turn on Enable Webhook Retry, MFT Gateway sends a failed delivery again and marks it with the mftg-wh-retry header. The listener responds before it runs your handler, so slow handlers don't cause retries, but a retry can still arrive after a network problem. Use messageId together with eventType to skip events you have already handled.

Compatibility

Version
Ballerina LanguageBallerina Swan Lake 2201.13.0

Quickstart

To use the Aayu MFT Gateway AS2 Trigger in your Ballerina application, update the .bal file as follows:

Step 1: Import the Aayu MFT Gateway AS2 Trigger Ballerina library

Copy
import ballerinax/aayu.mftg.as2.trigger as aayu;

Step 2: Initialize the Aayu MFT Gateway Listener

Initialize the trigger by providing the listener config and a port number/http:Listener object.

Copy
configurable aayu:ListenerConfig userInput = ?;
listener aayu:Listener aayuListener = new (userInput, 8090);

webhookSecret in userInput is the public key downloaded from MFT Gateway, set in Config.toml as shown in the Setup guide - this is what the trigger uses to verify incoming events actually came from MFT Gateway.

If you don't provide a port it will use the default port, which is 8090.

Copy
listener aayu:Listener aayuListener = new (userInput);

Step 3: Use the correct service type to implement the service

Each event has its own service type with a single remote function:

EventService typeRemote function
MESSAGE.RECEIVED.SUCCESSReceivedMessageServiceonMessageReceivedSuccess
MESSAGE.SEND.SUCCESSSentMessageServiceonMessageSendSuccess
MESSAGE.SEND.FAILEDFailedMessageServiceonMessageSendFailed
MESSAGE.SEND.INCOMPLETEIncompleteMessageServiceonMessageSendIncomplete

Step 4: Provide remote functions corresponding to the events you're interested in

Attach one service per event you want, all on the same listener - for example, aayu:ReceivedMessageService for received messages.

Copy
import ballerina/log;

service aayu:ReceivedMessageService on aayuListener {

    remote function onMessageReceivedSuccess(aayu:MessageReceivedEvent payload) returns error? {
        log:printInfo("AS2 message received", partner = payload.partnerName,
                subject = payload.messageSubject, attachments = payload.attachments);
    }
}

Step 5: Run the service

Use the bal run command to compile and run the Ballerina program.

Step 6: Register a webhook so MFT Gateway can reach your service

See Setup guide above for the full walkthrough (with screenshots) of exposing your service and registering the webhook, for both local testing and production use.

Examples

The aayu.mftg.as2.trigger module provides practical examples illustrating usage in various scenarios. Explore these examples, covering common AS2 event handling use cases.

Report issues

To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository.

Import

import ballerinax/aayu.mftg.as2.trigger;Copy

Other versions

0.9.0

Metadata

Released date: about 15 hours ago

Version: 0.9.0

License: Apache-2.0


Security

No known vulnerabilities in libraries

Checked on 2026-11-18 via OSV.dev


Compatibility

Platform: java21

Ballerina version: 2201.13.0

GraalVM compatible: Yes


Pull count

Total: 0

Current verison: 0


Weekly downloads


Source repository


Keywords

Name/Aayu MFTG AS2 Trigger

Area/Cloud & Infrastructure

Vendor/Aayu

Cost/Paid

Type/Trigger


Contributors