Subscribe to events

This guide describes how to subscribe to a specific event emitted by fulfillmenttools for a webhook URL, Microsoft Azure Service Bus, or Google Cloud Pub/Sub. This process uses the Eventing mechanism.

For more details on the Eventing API, refer to the REST API documentation.

Limitations

For all fulfillmenttools available events, users can create subscriptions to receive notifications. For any single event, such as ORDER_CREATED, a maximum of five subscriptions can be created.

Notification types

Webhook

The website webhook.site is a helpful tool for testing webhook subscriptions. It generates a unique URL that can be used for testing and allows the response code to be changed to simulate failing requests.

Use the generated URL in the callbackUrl field for the WEBHOOK target type, as shown in the Create a subscription section.

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:

Register an application in Microsoft Entra ID and save the Application (Client) ID and Directory (Tenant) ID.
Create a client secret (in Certificates & secrets) for the new application and save its Value.
Create an Azure Service Bus namespace and save the namespace name.
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.
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.

Google Cloud Pub/Sub

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

Define the topic where messages will be published.
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.

Contexts

For some events, it is 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, or
- for a 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"]
  }
]

Create a subscription

To create a subscription in fulfillmenttools to receive events, register for an event such as ORDER_CREATED. For this, use the following API call:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/subscriptions

{
    "name": "Web subscription for INVENTORY_FACILITY_STOCK_CHANGED",
    "event": "INVENTORY_FACILITY_STOCK_CHANGED",
    "target": {
        "type": "WEBHOOK",
        "callbackUrl": "<callbackUrl>",
        "headers": [
            {
                "key": "X-My-Auth",
                "value": "Basic ZnVsZmlsbG1lbnR0b29sczpp"
            }
        ]
    },
    "contexts": [
        {
            "type": "FACILITY_GROUP",
            "values": ["group-ref-1"]
        }
    ]
}

{
    "name": "Azure subscription for ORDER_CREATED",
    "event": "ORDER_CREATED",
    "target": {
        "type": "MICROSOFT_AZURE_SERVICE_BUS",
        "tenantId": "<tenantId>",
        "clientId": "<clientId>",
        "clientSecret": "<clientSecret>",
        "namespace": "<namespace>",
        "queueOrTopicName": "<queueOrTopicName>"
    }
}

{
    "name": "Pub/Sub subscription for ORDER_CREATED",
    "event": "ORDER_CREATED",
    "target": {
        "type": "GOOGLE_CLOUD_PUB_SUB",
        "projectId": "<projectId>",
        "topicId": "<topicId>"
    }
}

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

Trigger the event

To complete this guide, create a new order with the following API endpoint to trigger the ORDER_CREATED event:

POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/order

For more information about eventing on the fulfillmenttools platform, refer to the following pages:

Last updated 15 minutes ago