API documentationIncident ManagementFeedback

Subscribe to events

This guide describes subscribing to a specific event emitted by fulfillmenttools for a webhook URL or Microsoft Azure Service Bus. For this, the Eventing mechanism is used.

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

Preparation

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

For the Microsoft Azure Service Bus the fulfillmenttools API needs some different data:

  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:

Directory (Tenant) ID -> tenantId

Application (Client) ID -> clientId

Value of application secret -> clientSecret

namespace name -> namespace

Queue or Topic name -> queueOrTopicName

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 ORDER_CREATED",
    "event": "ORDER_CREATED",
    "target": {
        "type": "WEBHOOK",
        "callbackUrl": "<callbackUrl>",
        "headers": [
            {
                "key": "X-My-Auth",
                "value": "Basic ZnVsZmlsbG1lbnR0b29sczpp"
            }
        ],
    }
}

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

Trigger the event

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

POST https://your.api.fulfillmenttools.com/api/order

Success!

Congratulations, that's it to connect to specific events asynchronously. The event can be used, for example, to trigger further processes on the provided service or to integrate into existing infrastructure.

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

Last updated