fulfillmenttools
API documentationIncident ManagementFeedback
Developer Docs
Developer Docs
  • Developer docs
  • Getting Started
    • Quickstart
    • Integration tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
    • Free trial
  • Technical Basics
    • Access to fulfillmenttools
    • Feature status
    • Available regions
    • Backup policies
  • Connecting to fulfillmenttools
    • Client SDKs
    • commercetools connect
    • OpenID connect
      • Configure Microsoft Entra ID / Azure Active Directory
      • Configure Keycloak
  • API
    • Core concepts
      • Authentication & authorization
      • API Versioning & lifecycle
      • Assign user to jobs
      • Localization
      • Resource timestamps
      • Custom attributes
      • Article attributes
      • Recordable attributes
      • Data update guarantees
      • Rate limits & scaling
      • Retries
      • Performance on test vs. production systems
      • Load testing
    • API calls
      • Postman
      • cURL
      • GraphQL Explorer
    • GraphQL API
    • RESTful API
      • Pagination interface
      • RapiDoc
      • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an event
      • Available events
        • Event flows
      • Eventing example
      • Event export
  • Integration Guides
    • Basics
      • Article categories
      • Audits
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy (context-based multi-config DOMS)
    • Show sticker to clients
    • Stow jobs
  • More Integration Guides
    • Carrier management
      • Introduction to carrier configuration
      • Required data when operating carriers
      • Adding & connecting carriers to facilities
      • Custom carrier
    • Configurations for order fulfillment
      • Picking configuration
      • Packing configuration
      • Handover configuration
      • Printing and document configuration
      • Packing container types
      • Parcel tag configuration
      • Headless order fulfillment
      • Short-pick reasons
      • External documents in order fulfillment
      • Service jobs
      • Load units
      • Running sequence
    • DOMS - distributed order management system (routing)
    • External actions
    • Interfacility transfer
    • Notifications
    • Orders
      • Place your first order
      • Ship-from-store orders
      • Click-and-collect orders
      • Locked orders
      • Order with custom services
      • Bundled items in an order
      • Order process status
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Timing
  • Receiving events preparations
  • Attempts to resend messages that were not delivered successfully
Edit on GitHub
  1. API

Eventing

Last updated 1 month ago

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 . Business features are implemented using independent microservices that send and consume events.

Eventing is available for an callback-url and the .

Timing

Events are the mechanism of choice for decoupling services within a distributed system. From the publication to the message bus to the publication to the subscriptions, it usually takes milliseconds to a few seconds. In the worst case, when our backend services are scaling up, this can take up to 30 seconds.

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.

Receiving events preparations

A step-wise approach is needed before receiving your first event from fulfillmenttools. Only fulfillmenttools users with the role ADMINISTRATOR can create new subscriptions.

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:

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.

More Eventing-API information can be found here:

To create a subscription, take a look into the integration guide .

REST API documentation - Eventing
Subscribe to events
MACH principles
Microsoft Azure Service Bus
Typical time of event distribution
Exponential Backoff when retrying messages
Drawing
Drawing
Drawing