Get ready to receive orders
Manage order delegations
- OMS
- Business
Sylvius Ziegler
Business Analyst
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 type | Description |
---|---|
Order-confirmed | This 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-stock | This 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.
5xx
, webhooks are repeated for up to 2 days. You can make use of this functionality instead of rebuilding it on your own.item-out-of-stock
webhook.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.
Shops > Shop > Storefront > Checkout Settings > Admin API 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.)
{
"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
Property | Type | Description |
---|---|---|
id | INTEGER | Contains 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. |
address | OBJECT | Contain the billing and shipping address of the customer. |
shopCountry | OBJECT | Provide details about the shop country where this order was placed. |
cost | OBJECT | Shows details about the costs, such as the total costs, taxes, but also applied fees or discounts like vouchers. |
payment | ARRAY OBJECT | Shows details about the payment method, and the unique identifier of the PSP, so you can capture the payment or refund it. |
items | ARRAY OBJECT | Shows 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.
Get ready to receive orders
Sylvius Ziegler
Business Analyst