Ctrlk
API documentationIncident managementFeedback
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

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.

For production environments, we strongly recommend using Google Cloud Pub/Sub or Microsoft Azure Service Bus instead of Webhook subscriptions.

Message broker integrations provide improved reliability and resilience because the messaging platform can absorb temporary outages of consumer systems. They also typically achieve lower, more consistent event delivery latency than HTTP-based webhook endpoints.

Webhook subscriptions are best suited for testing, evaluation, or simple integrations, while Pub/Sub and Azure Service Bus are the recommended options for business-critical event processing.

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'll 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

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.

To publish fulfillmenttools messages to Microsoft Azure Service Bus in a target system, a few settings must be configured in the target system:

  1. Register an application in Microsoft Entra ID and save the Application (Client) ID and Directory (Tenant) ID.

  2. Create a client secret (in Certificates & secrets) for the new application and save its Value.

  3. Create an Azure Service Bus namespace and save the namespace name.

  4. Configure Access control (IAM), which stands for Identity and Access Management, for the Service Bus. Assign the Service Bus Sender role to the application created in step 1.

  5. Create a Queue or Topic within the namespace.

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

  • Directory (Tenant) ID corresponds to tenantId.

  • Application (Client) ID corresponds to clientId.

  • Value of application secret corresponds to clientSecret.

  • Namespace name corresponds to namespace.

  • Queue or Topic name corresponds to queueOrTopicName.

To publish fulfillmenttools messages to Google Cloud Pub/Sub in a target system, the following must be configured:

  1. Define the topic where messages will be published.

  2. In the topic's permissions, add the fulfillmenttools service account ocff-event-function@{YOUR-TENANT-NAME}.iam.gserviceaccount.com as a principal with the Pub/Sub Publisher role.

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

  • Google Cloud project id corresponds to projectId.

  • Google Cloud Pub/Sub topic id corresponds to topicId.

2

Access the endpoint

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.

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:

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

Example payloads

Webhook subscription

Google Pub/Sub subscription

Note: We don't set any pub/sub attributes.

Microsoft Azure subscription

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.

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.

Event scopes

An event scope defines which facilities or facility groups are included in an event type. A unique key identifies each scope and produces independent events.

Event scopes are currently supported for the INVENTORY_ARTICLE_AVAILABILITY_CHANGED event type only.

You can define the scope using facilityRefs and facilityGroupRefs. This can be:

  • No facilities or facility groups are configured: The event is emitted including all facilities in the network.

  • facilityRefs configured: The event is emitted, but only the explicitly listed facilities contribute to the data within the event.

  • facilityGroupRefs configured: The event is emitted, but only the facilities that are members of the referenced facility groups contribute to the data within the event.

Both fields can be combined. The event includes all resolved facilities from facilityRefs and facilityGroupRefs.

If a facility group is edited, the next event automatically reflects the updated facility group list. If a referenced facility or group is deleted, it's removed from the scope.

The speed at which editing or deleting is reflected in the aggregated availability values of emitted events depends on the size of the data in the event. For events with a small data set, the updated scope is usually completed before the next emitted event. For events with large data sets, this updated scope propagates gradually.

Create an event scope

Event scopes are managed via the event scope configuration API. The endpoint supports CREATE, GET, SEARCH, UPDATE, and DELETE operations.

Validation

The key field is mandatory and must be unique per tenant.

Limits

Constraint
Limit

Maximum number of event scopes per tenant

10

Maximum number of facilityRefs per event scope

50

Maximum number of facilityGroupRefs per event scope

5

Subscriptions

Events with an event scope follow the standard subscription model. No scope-specific subscription is required. A single subscription to this event type receives events from all configured scopes. The configurationScopeKey field in the payload identifies which scope produced a given event.

For details on creating subscriptions, see the Receiving events section.

Inventory article availability changed event

For the INVENTORY_ARTICLE_AVAILABILITY_CHANGED event, event scopes define which facilities contribute to an aggregated stock availability calculation and determine when a corresponding event is emitted. Rather than receiving one stock signal per facility, consumers receive one aggregated signal per configured scope whenever the aggregated values change.

This mechanism enables retailers to model independent fulfillment domains (such as all stores or all online warehouses) and receive separate, aggregated stock signals for each domain.

Event payload

The system emits one event per scope when the aggregated stockAvailability values for an article change. The event identifies the article by its tenantArticleId and includes the current aggregated values.

For a description of the individual stockAvailability fields, refer to Stock availability.

Last updated

Was this helpful?