Module aayu.mftg.as2.trigger
ballerinax/aayu.mftg.as2.trigger Ballerina library
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 partnerMESSAGE.SEND.SUCCESS: an AS2 message was sent to a trading partnerMESSAGE.SEND.FAILED: sending an AS2 message failedMESSAGE.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.
-
Expose port
8090with ngrok:ngrok http 8090Copy the
ForwardingURL ngrok prints out - this is your temporary public webhook URL.
-
In MFT Gateway, open Integrations > Webhooks from the left navigation menu and select the AS2 tab under General Configurations.
-
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.
-
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 themftg-wh-signatureheader; the listener checks it with this public key.
-
Put the whole public key, including the
-----BEGIN PUBLIC KEY-----and-----END PUBLIC KEY-----lines, in aConfig.tomlnext to your service (see Quickstart below), and run it withbal run:[<your_org>.<your_module_name>.userInput] webhookSecret = """-----BEGIN PUBLIC KEY----- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA... -----END PUBLIC KEY-----""" -
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.
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 Language | Ballerina 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
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.
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.
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:
| Event | Service type | Remote function |
|---|---|---|
MESSAGE.RECEIVED.SUCCESS | ReceivedMessageService | onMessageReceivedSuccess |
MESSAGE.SEND.SUCCESS | SentMessageService | onMessageSendSuccess |
MESSAGE.SEND.FAILED | FailedMessageService | onMessageSendFailed |
MESSAGE.SEND.INCOMPLETE | IncompleteMessageService | onMessageSendIncomplete |
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.
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.
Useful links
- For more information go to the
aayu.mftg.as2.triggerpackage. - If you're moving from the older
trigger.aayu.mftg.as2package, see the migration notes. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.
Import
import ballerinax/aayu.mftg.as2.trigger;Other versions
0.9.0