Tutorial

Let's subscribe to Events!

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

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

Create the listening service

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

This tool is just a suggestion. You can also setup 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

Creating the subscription at fulfillmenttools

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

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/subscriptions' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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)"
}'

201 Created

{
    "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 has been created.

Trigger the event

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

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/orders' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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!"
                    },
                    {
                        "category": "descriptive",
                        "priority": 200,
                        "key": "Best-Price",
                        "value": "17,96 EUR"
                    },
                    {
                        "category": "descriptive",
                        "priority": 300,
                        "key": "Cut",
                        "value": "Women"
                    },
                    {
                        "category": "descriptive",
                        "priority": 400,
                        "key": "Material",
                        "value": "100% Cotton"
                    },
                    {
                        "category": "descriptive",
                        "priority": 500,
                        "key": "Article No.",
                        "value": "2020249"
                    },
                    {
                        "category": "descriptive",
                        "priority": 600,
                        "key": "Size",
                        "value": "S"
                    },
                    {
                        "category": "descriptive",
                        "priority": 700,
                        "key": "Decription",
                        "value": "Rotes T-Shirt mit weißen Streifen an den Ärmeln, Blockdruck mit Schriftzug auf der Brust"
                    }
                ]
            },
            "quantity": 1,
            "scannableCodes": [
                "2020249"
            ]
        }
    ]
}
'

201 Created

<Response body ommitted>

A couple of seconds later the event is being 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!"
            },
            {
              "category": "descriptive",
              "priority": 200,
              "key": "Best-Price",
              "value": "17,96 EUR"
            },
            {
              "category": "descriptive",
              "priority": 300,
              "key": "Cut",
              "value": "Women"
            },
            {
              "category": "descriptive",
              "priority": 400,
              "key": "Material",
              "value": "100% Cotton"
            },
            {
              "category": "descriptive",
              "priority": 500,
              "key": "Article No.",
              "value": "2020249"
            },
            {
              "category": "descriptive",
              "priority": 600,
              "key": "Size",
              "value": "S"
            },
            {
              "category": "descriptive",
              "priority": 700,
              "key": "Decription",
              "value": "Rotes T-Shirt mit weißen Streifen an den Ärmeln, Blockdruck mit Schriftzug auf der Brust"
            }
          ]
        },
        "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 gets 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 in an asynchronous way. The event can be used for example to trigger further processes on the provided service or to integrate into existing infrastructure.