Eventing

The fulfillmenttools eventing mechanism doesn't guarantee event ordering. 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.

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 fulfillmenttools to an external system:

Typical time of event distribution

Avoid event delivery delays

In a distributed system, it's expected that parts of the system will fail from time to time. However, when running a service on your own that serves as an endpoint for subscriptions, it's important to properly monitor its availability and return codes to ensure events are delivered on time.

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

Receiving events

For all Available events, subscriptions can be created using the eventing API to receive notifications.

Prerequisites

• Access to your company's tenant (projectId and credentials)

• Have an authenticated session in Postman

• Have an Administrator role

• Imported the fulfillmenttools Postman collection

Limitations

For any single event, such as ORDER_CREATED, a maximum of five subscriptions can be created.

In the below example, we set up a subscription for the order created event.

1

Set up your preferred provider

Use the tabs below to select the relevant provider instructions needed for set up

Webhook

Visit webhook.site to generate a unique URL that can be used for testing and allows the response code to be changed to simulate failing requests.

The following values are then used for the subscription API call in fulfillmenttools:

GET url corresponds to callbackURL.

Microsoft Azure Service Bus

Google Cloud Pub/Sub

2

Access the endpoint

POST https://{projectId}.api.fulfillmenttools.com/api/subscriptions

In the Postman collection, you can select the relevant provider for this endpoint.

3

Register the event

Update the parameters in the body for the relevant settings you created in step one for your provider.

Webhook

Body

{
    "name": "Order created (Webhook)",
    "event": "ORDER_CREATED",
    "target": {
        "type": "WEBHOOK",
        "callbackUrl": "callbackURL",
        "headers": [
            {
                "key": "header-key",
                "value": "header-value"
            }
        ]
    }
}

Microsoft Azure Service Bus

Google Cloud Pub/Sub

A successful request returns a 201 Created status, and the subscription becomes active immediately.

4

Test the notification

Create a new test order with the follow endpoint to trigger the ORDER_CREATED event:

POST https://{projectId}.api.fulfillmenttools.com/api/order

A successful request returns a 201 Created status, and you should receive a notification on your provider service of the order.

Contexts

For the INVENTORY_FACILITY_STOCK_CHANGED event, it's possible to specify contexts to further restrict when a subscription is triggered.

• If contexts are specified, the subscription is triggered only if all contexts apply.

• Available context types are FACILITY and FACILITY_GROUP.

• An event applies if it occurs for a:

  • Facility explicitly listed in the context

  • Facility that belongs to one of the specified facility groups

• If the event is a bulk event containing multiple payloads, the payloads are filtered to include only those relevant to the specified contexts.

"contexts": [
  {
    "type": "FACILITY",
    "values": ["facility-ref-1", "facility-ref-2"]
  },
  {
    "type": "FACILITY_GROUP",
    "values": ["group-ref-1"]
  }
]

Attempts to resend messages that weren't delivered successfully

fulfillmenttools follows the exponential backoff pattern when a configured subscription is unreachable or returns a response code other than 200 OK. If this happens, fulfillmenttools will automatically initiate a retry. The time between the retries will progressively increase with every retry from 20 seconds until it reaches 600 seconds. This is executed for one hour.

Redelivery attempts continue at this maximum interval until one of the following occurs:

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

• The event's 7-day retention period has expired, at which point it's permanently dropped and deleted.

fulfillmenttools can't guarantee how many times or the interval between retries after one hour.

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.

fulfillmenttools doesn't monitor the health or availability of subscriber endpoints.

Monitoring and alerting

It's 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.

Event flow examples

fulfillmenttools communicates relevant changes through events. The flowcharts below provide a brief overview of a subset of processes and the events they trigger.

A comprehensive overview of all events is available in the Available events article.

The flows below are examples of a standard, successful process in fulfillmenttools. The exact sequence of flows and events can differ depending on the specific configuration of modules and processes.

The eventing API does not guarantee the order of events.

Order, reservations, and fulfillment

The following diagram depicts the typical events emitted during an exemplary order fulfillment process. This includes order routing, reservations, picking, packing, and handover, as well as a potential return.

Inbound process

The following diagram depicts the typical events emitted during an exemplary inbound process, from the creation of a Purchase Order (PO) to the receipt of goods.

Stow jobs

The following diagram depicts the typical events emitted during an exemplary stowing process, from the creation of a stowJob to the stowing of the final items and the completion of the job.