AS2 Gateway Real-time Notification Webhooks

Overview

Webhooks - a Quick Introduction

A webhook sends you notifications of events - such as when a new message is received. It is similar to the concept of callbacks in some programming/scripting languages, but instead works over a network protocol - usually HTTP(S).

You can configure AS2 Gateway to send webhook notifications for incoming AS2 messages and MDNs (sync/async). This is very convenient in comparison to other mechanisms for checking incoming data (such as listing unread messages via V1 API), because:

  • you no longer have to repeatedly poll AS2 Gateway for new data (like the abovementioned API endpoint, or the SFTP inbox) - in other words, your system can stay passive while AS2 Gateway will actively push data to it

  • there is no redundancy (every webhook event corresponds to an actual receive), unlike in polling (where your system would need to keep on communicating, even when there is no new data); this saves the associated processing power and bandwidth on your end

  • you are automatically notified of incoming messages/MDNs very quickly, usually within a matter of seconds

  • you can use the webhook endpoint to fire/initiate your own custom workflows, leveraging it as a trigger/ingress point in your B2B pipeline without having to resort to internal cronjobs etc.

How AS2 Gateway Webhooks Work

  1. You create and deploy a webhook, which is a simple HTTP endpoint (request handler) that can handle the notification data posted by AS2 Gateway in a desired format.

  2. You add a webhook configuration entry on AS2 Gateway side, pointing to the above URL, along with the desired payload format setting.

  3. When a new AS2 message (or MDN) is received, AS2 Gateway automatically sends a HTTP POST request to your endpoint, containing details of the received message.

  4. Your handler processes the received details in the posted data, and decides on the next action - such as fetching the message content (files/attachments) via a Download-Attachments V1 API call or a SFTP get on the inbox, or simply passing along the AS2 message ID to the the next component in your order-processing pipeline.

Limitations

These refer to the AS2 Gateway webhook feature at the time of writing; some of they may already be improved/rectified.

  • Raw-payload mode of received-message webhooks does not support multiple attachments; if you receive several files in one AS2 message, you will only receive the content of the first file in the webhook payload.

  • For HTTPS webhook endpoints, additional steps may be required if the TLS certificate is not trusted (i.e. if the certificate is self-signed or issued by an untrusted party).

  • Webhook requests are best-effort, and currently do not offer guaranteed delivery (i.e. are not automatically retried) and neither manual retries; if your endpoint fails due to some reason, AS2 Gateway will not invoke the webhook again for the same message/MDN. While the AS2 Gateway Team is working on improving the retry mechanisms, you can mitigate this using a hybrid approach - such as marking each message as read upon successful download/processing, and adding a SFTP/API based polling logic (at a slow rate) to capture any "skipped" messages that have remained unprocessed (unread) for more than a few minutes. Additionally, if there is a failure in pushing any of the production notifications on AS2 Gateway side, the team will notify you via alternative channels.

  • Webhooks cannot currently be configured via the AS2 Gateway web console (browser UI). Please open a support request with AS2 Gateway Team if you wish to add a new webhook or modify an existing one.

In this topic
In this topic