Eventing

Asynchronous communication from fulfillmenttools towards customer services by leveraging webhooks.

The fulfillmenttools eventing mechanism does not guarantee the order of events. Furthermore, the same event can be emitted multiple times.

Eventing is the mechanism that notifies external systems about business events, such as Order has been routed or pick job has been completed. Events are phrased in the past tense because they describe actions that have already occurred.

fulfillmenttools' platform architecture follows the MACH principles. Business features are implemented using independent microservices that send and consume events.

Eventing is available for a callback URL, the Microsoft Azure Service Bus, and Google Cloud Pub/Sub.

Timing

Events are the primary mechanism for decoupling services within a distributed system. The time from publication on the message bus to delivery to a subscription is typically a few milliseconds to several seconds. In worst-case scenarios, such as when backend services are scaling up, this process can take up to 30 seconds.

The following diagram shows the typical timing of events originating from the fulfillmenttools platform to an external system:

Typical time of event distribution

Avoid Event Delivery Delays

In a distributed system, it is expected that parts of the system will fail every now and then. However, when running a service on your own that serves as an endpoint to subscriptions, it is important that you properly monitor the availability and return codes it returns to prevent events from being delivered in time.

Services returning a 200 OK response are considered error-free.

Preparing to receive events

Before an endpoint can receive events from fulfillmenttools, a subscription must be created via the Eventing Application Programming Interface (API). Only users with the ADMINISTRATOR role can create new subscriptions.

For more details, see the Eventing section in the REST API documentation.

To create a subscription, take a look at the integration guide Subscribe to events.

Attempts to resend messages that were not delivered successfully

The time between the retries will progressively increase with every retry from 20 seconds until it reaches 600 seconds. This is executed for 1 hour. After 1 hour fulfillmenttools still tries to deliver events for 7 days. Nevertheless, fulfillmenttools cannot give any guarantees on how many times and the interval between retries.

If fulfillmenttools can't deliver an event for 7 days, the message will be dropped and it is lost forever.

fulfillmenttools does not monitor the endpoints to which the events should be delivered.

When a configured subscription is not reachable or answers with another response code than HTTP 200 OK the fulfillmenttools platform will automatically initiate a retry of the message. The pattern followed is described as exponential backoff, which basically means that the time that goes by between the actual retry attempts progressively increases. Please see the following diagram that visualizes the approach:

Diagram of an exponential backoff pattern for retrying messages, starting with a 20-second delay and increasing to a maximum of 600 seconds.

The first redelivery attempt occurs after 20 seconds. The interval between subsequent attempts increases until it reaches a maximum of 600 seconds (10 minutes). Redelivery attempts continue at this maximum interval until one of the following occurs:

• The subscription endpoint acknowledges the event by returning an HTTP 200 OK response.

• The event's retention period of seven days is reached, at which point the event is permanently dropped.

Note that fulfillmenttools does not monitor the health or availability of subscriber endpoints.

Monitoring and Alerting

It is recommended to monitor the subscription endpoint and employ an alerting mechanism to detect failures early, preventing events from being dropped after the retention period expires.