docs
  1. SCAYLE Resource Center
  2. Onboarding Guide
  3. Onboarding: Backend
  4. Get Ready to Receive Orders

Get Ready to Receive Orders

Since this guide covers the most basic backend configurations and integrations, we’ll assume you have a working front end and checkout in place. If you’re wondering how to get your front end up and running, refer to the relevant guide.

This section will focus on using webhooks to receive notifications when an order is placed. We’ll teach you about what a webhook is, how to subscribe to one, and how to process them when receiving an order.

SCAYLE supports several webhooks that can inform subscribed systems about events happening in SCAYLE. Please refer to Webhook Overview for more information.

This chapter will focus on 2 different types of webhooks: Both webhooks are non-blocking webhooks, meaning they are asynchronous and therefore do not block the customer’s actions.

In other words, the customer won’t see a loading icon and need to wait. The response from an external system doesn't affect the process logic. These types of webhooks serve as notification channels only. SCAYLE also supports blocking webhooks in some cases.

Please refer to Blocking Webhooks for more information.

Webhook typeDescription
Order-confirmedThis webhook is triggered when an order is successfully confirmed in SCAYLE. The confirmation happens after a user clicks on “confirm order” in the last step of the checkout flow and is then redirected to the order success page. At this step, the payment has been successfully authorized.
Item-out-of-stockThis webhook is triggered when items of a confirmed order cannot be fulfilled after considering Backbone’s virtual stock handling. This is a rare case but should be covered by canceling those items also on the receiver's side.

To receive webhooks, you need an external system that can receive HTTP requests.

You can subscribe to webhooks in 2 different ways. You can either use the Admin API, outlined here, or via the SCAYLE Panel. In most cases, you’ll subscribe to just webhooks once and not make any further changes, so we recommend doing it via the SCAYLE Panel as described here.

You can subscribe to as many webhooks as you need, and subscribing to one webhook covers all shop countries within a shop. For example, if you subscribe to the order-confirmed webhook in a specific shop country of a shop that has multiple shop countries, the subscription also counts for all other shop countries, but not for other shops. It may take up to 5 minutes for a new subscription to become active.

Tips for integrating webhooks

  • Webhooks come with an integrated retry mechanism. If the downstream service responds with an error code like 5xx, webhooks are repeated for up to 2 days. You can make use of this functionality instead of rebuilding it on your own.
  • Consider that webhooks are not guaranteed to be sent or received in the correct order. Your downstream system must be able to handle that. Keep this in mind especially when dealing with the order-confirmed and the item-out-of-stock webhook.
  • We recommend securing your receiving web service by using basic auth.
  • Your system should be able to handle concurrent requests.
  • Ensure idempotency in your system because we cannot guarantee that the webhook will only be delivered once.

Subscribe to webhooks and manage them

As previously mentioned, subscribing to a specific webhook in one shop country means the webhook is valid for all other shop countries. As we created three country shops for our Fashion Store (see Shop Structure), we only need to add the webhook subscription to one shop country.

Add webhooks

  1. Go to Shops > Shop > Storefront > Checkout Settings > Admin API Webhooks
  2. Click Add New Webhook and enter Version, URL fields as well as the Type of webhook event you would like to subscribe to.

Admin webhooks

The URL should reflect the downstream service that receives the event. You can add basic auth to the URL. In our case, we assume the endpoint is not protected (not recommended).

We also assume that the URL is the same for all shop countries. Then click save.

It may take up to 5 minutes for a new subscription to become active.

Then repeat the same process with the item-out-of-stock event.

To understand the entire webhook payload, see available webhook events. You can also find another example here.

Let’s assume we’ve already received our first order, placed in the German shop country. The corresponding payload would look like this (we’ve simplified the payload in this case.)

Simplified payload
{
    "key": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "meta":
    {
        "xRequestId": "1798e99a-711f-4f06-ae4c-ce86ed1331b8"
    },
    "occurredAt": "2023-11-06T15:01:26+02:00",
    "type": "order-confirmed",
    "payload":
    {
        "address":
        {
            "billing":
            {
                "id": 998,
                "street": "Street",
                "houseNumber": "1",
                "additional": "erste Stock",
                "zipCode": "123456",
                "city": "Hamburg",
                "countryCode": "DEU",
                "isDefault":
                {
                    "billing": false,
                    "shipping": true
                },
                "recipient":
                {
                    "firstName": "John",
                    "gender": "m",
                    "lastName": "Doe",
                    "title": "Prof."
                }
            },
            "shipping":
            {
                "id": 998,
                "street": "Street",
                "houseNumber": "1",
                "additional": "erste Stock",
                "zipCode": "123456",
                "city": "Hamburg",
                "countryCode": "DEU",
                "isDefault":
                {
                    "billing": false,
                    "shipping": true
                },
                "recipient":
                {
                    "firstName": "John",
                    "gender": "m",
                    "lastName": "Doe",
                    "title": "Prof."
                }
            }
        },
        "basketKey": "basket-c6v7k4eer1",
        "confirmedAt": "2023-11-07 14:30:27",
        "cost":
        {
            "tax":
            {
                "vat":
                {
                    "amount": 11
                }
            },
            "withTax": 1390,
            "withoutTax": 1168
        },
        "currencyCode": "EUR",
        "customer":
        {
            "id": 9876
        },
        "id": 123,
        "items":
        [
            {
                "id": 1,
                "packageId": 1,
                "price":
                {
                    "tax":
                    {
                        "vat":
                        {
                            "amount": 190,
                            "rate": 1
                        }
                    },
                    "withTax": 1190,
                    "withoutTax": 1000
                },
                "product":
                {
                    "id": 1,
                    "referenceKey": "FS-100-black"
                },
                "key": "ac834d23e689u678",
                "status": "available",
                "variant":
                {
                    "id": 1,
                    "referenceKey": "FS-100-black-S"
                },
                "warehouseId": 1
            }
        ],
        "packages":
        [
            {
                "carrierKey": "dhl",
                "deliveryDate":
                {
                    "maximum": "2023-11-08",
                    "minimum": "2023-11-12"
                },
                "deliveryStatus": "open",
                "id": 1
            }
        ],
        "payment":
        [
            {
                "amount": 1190,
                "data":
                {
                    "CCBrand": "VISA",
                    "CCExpiry": "202005",
                    "IPCity": "charlottenburg",
                    "IPLatitude": "52.5151",
                    "IPLongitude": "13.3053",
                    "IPState": "berlin",
                    "IPZone": "276",
                    "IPZoneA2": "de"
                },
                "key": "computop_creditcard",
                "transactionKey": "creditcard-abcde"
            }
        ],
        "shopCountry":
        {
            "id": 1,
            "shopKey": "fs",
            "countryCode": "DE",
            "defaultLanguageCode": "de_DE",
            "supportedLanguageCodes":
            [
                "de_DE"
            ],
            "active": true,
            "deleted": false,
            "url": "www.example.com",
            "currencyCode": "EUR"
        }
    }
}

Note the following information with regard to this payload

PropertyTypeDescription
idINTEGERContains the unique identifier of the order. You’ll need this to send order updates later on. The identifier is unique across all shop countries you created.
addressOBJECTContain the billing and shipping address of the customer.
shopCountryOBJECTProvide details about the shop country where this order was placed.
costOBJECTShows details about the costs, such as the total costs, taxes, but also applied fees or discounts like vouchers.
paymentARRAY OBJECTShows details about the payment method, and the unique identifier of the PSP, so you can capture the payment or refund it.
itemsARRAY OBJECTShows all ordered items. Each element represents a single line item. Even if the customer purchased the same variant twice, you would see two elements within the array.

You've subscribed to two webhooks for all your shop countries.
Now you’ll be notified when someone places an order or an item is out of stock.

Further education - SCAYLE Academy

Provide Feedback