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

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

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

Register an application in Microsoft Entra ID and save Application (Client) ID and Directory (Tenant) ID.
Create a client secret (in Certificates & secrets) for the new application and save the Value of it.
Create an Azure Service Bus namespace and save the namespace name.
Create Access control (IAM) for the Service Bus, with the role Service Bus Sender, and select as a member the created application.
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:

The topic must be defined on which the message should be published.
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

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"
            }
        ],
    }
}

{
    "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 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.api.fulfillmenttools.com/api/order

Success!

Congratulations, that's how 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 2 months ago