Eventing
Last updated
Last updated
The fulfillmenttools eventing mechanism does not guarantee the correct ordering of events. Furthermore, the same event can be emitted multiple times.
Eventing is how the fulfillmenttools platform allows external systems to be notified about business events such as "Order has been routed" or "Pickjob has been completed". Please note that Events are always phrased in the past tense because they describe events that have already happened.
The fulfillmenttools platform's architecture follows the MACH principles. Business features are implemented using independent microservices that send and consume events.
Events are the mechanism of choice for decoupling services within a distributed system. The following diagram shows the typical timing of events originating from the fulfillmenttools platform to an external system:
Avoid delays in event sending due to subscriptions in error
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.
A step-wise approach is needed before receiving your first event from fulfillmenttools. Currently, only fulfillmenttools users with the role ADMINISTRATOR can create new subscriptions.
More Eventing-API information can be found here: REST API documentation - Eventing
To create a subscription, use the following API endpoint:
name - Name of the subscription, which helps identify the subscription.
callbackUrl - A publicly available endpoint on the internet. It has to provide access via the HTTPS protocol.
event - Name of the fulfillmenttools event you are interested in.
headers - The headers fulfillmenttools should send along the event request. It is suggested that some kind of authorization header be provided (e.g. Authorization) in order to allow your service to check authorized access to your endpoint.
The time between the retries will progressively increase with every retry from 20 seconds until it reaches 600 seconds. After 7 days the message will be dropped.
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:
As you can see above, when a message cannot be delivered for the first time, there is currently a first retry after 20 seconds. Retries are being performed after every failed attempt. The time between the retries will progressively increase with every retry until it reaches 600 seconds (10 minutes). It will stay at that rate until either
the subscription is reachable & acknowledges the message by replying with HTTP 200 OK or
message retention is reached (currently: 7 days). It will be dropped then.
Monitoring and alerting
We recommend monitoring your subscription endpoint and using an alerting mechanism to detect failures early before the messages are dropped.
