Subscribing to events

In this tutorial, we will subscribe to a specific event emitted by fulfillmenttools. We will use the Eventing mechanism.

Create the event listener

First, we need to create a web endpoint that is publicly available on the internet. For the sake of this tutorial, we will leverage a service called https://webhook.site/. It allows you to create a web endpoint in a few seconds to print out the incoming requests.

This tool is just a suggestion. You can also set up a webhook on your local machine using, for example, https://ngrok.com/ or even create a fully running service in your infrastructure.

In the end, we need to have an exposed endpoint. In this example, we will use the callbackURL https://webhook.site/1c90a559-dd18-4e45-95ec-04821d705466, which is provided by webhook.site.

The service webhook.site after the webhook has been created

Create the subscription at fulfillmenttools

Now that we have our service up and running, we can create a subscription to fulfillmenttools to receive events. We will register for the ORDER_CREATED event by issuing the following call:

POST https://{YOUR_TENANT_NAME}.api.fulfillmenttools.com/api/subscriptions

{
    "callbackUrl": "https://webhook.site/1c90a559-dd18-4e45-95ec-04821d705466",
    "event": "ORDER_CREATED",
    "headers": [
        {
            "key": "X-My-Auth",
            "value": "Basic ZnVsZmlsbG1lbnR0b29sczppc2Jlc3Q="
        }
    ],
    "name": "Tutorial Subscription (not for productive use)"
}

If your request was successful, you'll receive a HTTP 201 created response with a body similar to this:

{
     "callbackUrl": "https://webhook.site/1c90a559-dd18-4e45-95ec-04821d705466",
    "event": "ORDER_CREATED",
    "headers": [
        {
            "key": "X-My-Auth",
            "value": "Basic ZnVsZmlsbG1lbnR0b29sczppc2Jlc3Q="
        }
    ],
    "name": "Tutorial Subscription (not for productive use)",
    "id": "76335286-5e68-434a-b620-e00f953dd098",
    "created": "2022-12-21T17:47:36.650Z",
    "lastModified": "2022-12-21T17:47:36.650Z"
}

That's it. You just created your very first subscription, which is triggered whenever an Order is created.

Trigger the event

To complete this tutorial, we need to create an Order and see whether the subscription to the event ORDER_CREATED works.

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

{
    "orderDate": "2022-12-22T08:16:07.000Z",
    "consumer": {
        "addresses": [
            {
                "street": "Schanzenstr.",
                "houseNumber": "30",
                "postalCode": "51063",
                "city": "Cologne",
                "country": "DE",
                "firstName": "Luke",
                "lastName": "Skywalker"
            }
        ]
    },
    "tenantOrderId": "FC-4711-2361",
    "orderLineItems": [
        {
            "article": {
                "tenantArticleId": "2020249",
                "title": "T-Shirt \"Am Sonnenhut\"",
                "attributes": [
                    {
                        "category": "descriptive",
                        "priority": 100,
                        "key": "%%subtitle%%",
                        "value": "Newly arrived!"
                    }
                ]
            },
            "quantity": 1,
            "scannableCodes": [
                "2020249"
            ]
        }
    ]
}
'

The endpoint should respond with 201 created

A couple of seconds later, the event was delivered to our client. It is shown in the following way:

Screenshot

Complete answer:

Headers:
connection	close
content-length	1422
content-type	application/json
x-my-auth	Basic ZnVsZmlsbG1lbnR0b29sczppc2Jlc3Q=
accept-encoding	gzip, deflate
host	webhook.site
traceparent	00-c922c8509f5d7482787d97d8040716c5-64dcf668569bfcc9-01

Body:
{
  "event": "ORDER_CREATED",
  "payload": {
    "orderDate": "2022-12-22T08:16:07.000Z",
    "consumer": {
      "addresses": [
        {
          "street": "Schanzenstr.",
          "houseNumber": "30",
          "postalCode": "51063",
          "city": "Cologne",
          "country": "DE",
          "firstName": "Luke",
          "lastName": "Skywalker"
        }
      ]
    },
    "tenantOrderId": "FC-4711-2361",
    "orderLineItems": [
      {
        "article": {
          "tenantArticleId": "2020249",
          "title": "T-Shirt \"Am Sonnenhut\"",
          "attributes": [
            {
              "category": "descriptive",
              "priority": 100,
              "key": "%%subtitle%%",
              "value": "Newly arrived!"
            }
          ]
        },
        "quantity": 1,
        "scannableCodes": [
          "2020249"
        ],
        "id": "d0a54077-1427-457c-9859-01ec7d13adb4"
      }
    ],
    "deliveryPreferences": {
      "shipping": {
        "serviceLevel": "DELIVERY"
      }
    },
    "status": "OPEN",
    "id": "0fa8b609-7038-4450-85b1-1ca2fe7c7f9d",
    "tags": [],
    "processId": "a72007e1-d04a-4c38-8079-c2aec8a5034f",
    "created": "2022-12-21T17:54:34.967Z",
    "lastModified": "2022-12-21T17:54:34.967Z",
    "schemaVersion": 1,
    "version": 1
  },
  "eventId": "5993095975110686"
}

Please take note of the x-my-auth header, which we supplied when creating the subscription. Also, the event includes an eventId, the event name and, of course, the entity itself as payload.

Success!

You just finished this tutorial showing 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:

• Eventing

• Structure of an Event

• Available Events