# Eventing
{% hint style="warning" %}
The fulfillmenttools eventing mechanism doesn't guarantee event ordering. The same event can be emitted multiple times.
{% endhint %}
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](https://learn.microsoft.com/en-gb/azure/service-bus-messaging/), and [Google Cloud Pub/Sub](https://docs.cloud.google.com/pubsub/docs/overview).
## 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:
{% hint style="danger" %}
**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.
{% endhint %}
## Receiving events
For all [available-events](https://docs.fulfillmenttools.com/documentation/getting-started/eventing/available-events "mention"), subscriptions can be created using the eventing API to receive notifications.
{% hint style="success" %}
### 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
{% endhint %}
{% hint style="warning" %}
### Limitations
For any single event, such as `ORDER_CREATED`, a maximum of five subscriptions can be created.
{% endhint %}
In the below example, we set up a subscription for the order created event.
{% stepper %}
{% step %}
**Set up your preferred provider**
Use the tabs below to select the relevant provider instructions needed for set up
{% tabs %}
{% tab title="Webhook" %}
Visit [webhook.site](https://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`.
{% endtab %}
{% tab title="Microsoft Azure Service Bus" %}
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`.
{% endtab %}
{% tab title="Google Cloud Pub/Sub" %}
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`.
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Access the endpoint**
```http
POST https://{projectId}.api.fulfillmenttools.com/api/subscriptions
```
{% hint style="info" %}
In the Postman collection, you can select the relevant provider for this endpoint.
{% endhint %}
{% endstep %}
{% step %}
**Register the event**
Update the parameters in the body for the relevant settings you created in step one for your provider.
{% tabs %}
{% tab title="Webhook" %}
{% endtab %}
{% endtabs %}
A successful request returns a `201 Created` status, and the subscription becomes active immediately.
{% endstep %}
{% step %}
**Test the notification**
Create a new test order with the follow endpoint to trigger the `ORDER_CREATED` event:
```http
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.
{% endstep %}
{% endstepper %}
### 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.
```json
"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.
{% hint style="info" %}
fulfillmenttools can't guarantee how many times or the interval between retries after one hour.
{% endhint %}
See the following diagram that visualizes the approach:
{% hint style="warning" %}
fulfillmenttools doesn't monitor the health or availability of subscriber endpoints.
{% endhint %}
{% hint style="info" %}
**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.
{% endhint %}
## 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](https://docs.fulfillmenttools.com/documentation/getting-started/eventing/available-events).
{% hint style="info" %}
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.
{% endhint %}
{% hint style="warning" %}
The eventing API does not guarantee the order of events.
{% endhint %}
### 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.
{% hint style="danger" %}
**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.
{% endhint %}
## Receiving events
For all [available-events](https://docs.fulfillmenttools.com/documentation/getting-started/eventing/available-events "mention"), subscriptions can be created using the eventing API to receive notifications.
{% hint style="success" %}
### 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
{% endhint %}
{% hint style="warning" %}
### Limitations
For any single event, such as `ORDER_CREATED`, a maximum of five subscriptions can be created.
{% endhint %}
In the below example, we set up a subscription for the order created event.
{% stepper %}
{% step %}
**Set up your preferred provider**
Use the tabs below to select the relevant provider instructions needed for set up
{% tabs %}
{% tab title="Webhook" %}
Visit [webhook.site](https://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`.
{% endtab %}
{% tab title="Microsoft Azure Service Bus" %}
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`.
{% endtab %}
{% tab title="Google Cloud Pub/Sub" %}
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`.
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Access the endpoint**
```http
POST https://{projectId}.api.fulfillmenttools.com/api/subscriptions
```
{% hint style="info" %}
In the Postman collection, you can select the relevant provider for this endpoint.
{% endhint %}
{% endstep %}
{% step %}
**Register the event**
Update the parameters in the body for the relevant settings you created in step one for your provider.
{% tabs %}
{% tab title="Webhook" %}
{% hint style="warning" %}
fulfillmenttools doesn't monitor the health or availability of subscriber endpoints.
{% endhint %}
{% hint style="info" %}
**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.
{% endhint %}
## 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](https://docs.fulfillmenttools.com/documentation/getting-started/eventing/available-events).
{% hint style="info" %}
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.
{% endhint %}
{% hint style="warning" %}
The eventing API does not guarantee the order of events.
{% endhint %}
### 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.
