API documentationIncident ManagementFeedback
Edit

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. For this, the Eventing mechanism is used.

More Eventing-API information can be found here: REST API documentation - Eventing

Limitations

For all fulfillmenttools available events, subscriptions can be created to receive notifications (Webhook, Microsoft Azure Service Bus, Google Cloud Pub/Sub). For every single event, such as ORDER_CREATED, a maximum of five subscriptions is possible.

Notification types

Webhook

For subscription testing the website webhook.site is very helpful. This creates a unique URL that could be used for webhook testing. Furthermore, the response code can be changed to simulate failing requests due to a failed system.

Use the generated URL to use it in the callbackUrl field for the WEBHOOK case (see Create a subscription at fulfillmenttools).

Microsoft Azure Service Bus

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

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

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

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

  4. Create Access control (IAM) for the Service Bus, with the role Service Bus Sender, and select as a member the created application.

  5. Create in the namespace a Queue or Topic.

Now the following values must be used for the subscription API call on the fulfillmenttools platform (an example can be found below):

Directory (Tenant) ID -> tenantId

Application (Client) ID -> clientId

Value of application secret -> clientSecret

Namespace name -> namespace

Queue or Topic name -> queueOrTopicName

Google Cloud Pub/Sub

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

  1. The topic must be defined on which the message should be published.

  2. Inside this topic, the fulfillmenttools service account ocff-event-function@{your-tenant-name}.iam.gserviceaccount.com must be added as principal with the role Pub/Sub Publisher.

Now, the following values must be used for the subscription API call on the fulfillmenttools platform (an example can be found below):

Google Cloud project id -> projectId

Google Cloud Pub/Sub topic id -> topicId

Contexts

For some events, it is now possible to specify contexts to further restrict when a subscription is triggered.

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

  • Available context types are:

    • FACILITY

    • FACILITY_GROUP

  • An event applies if it happens:

    • for a facility explicitly listed in the context, or

    • for a facility that belongs to one of the mentioned facility groups.

  • If the event is a bulk event and contains 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 at fulfillmenttools

To create a subscription at fulfillmenttools to receive events, register e.g. for the ORDER_CREATED event. 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"]
        }
    ]
}

A successful request returns with an HTTP 201 created and the subscription is active.

Trigger the event

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

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

To learn more about eventing on the fulfillmenttools platform, please check out the following pages:

PreviousSearchNextSticker

Last updated