Overview

General

Webhooks offer a powerful mechanism for delivering real-time notifications to other systems when specific events occur within SCAYLE. It is handy if you need to trigger an action in your system after a specific SCAYLE event occurs. This enables you to create seamless integrations that efficiently react to these events without the need for constant API polling.

This guide will walk you through the general idea behind webhooks, outline useful examples, and guide you through all the necessary steps of subscribing to and working with webhooks.

Usage examples

• Inform about order creation, changes in orders, returns or refunds to shipping companies
• Integrate your accounting software with order data
• Remove customer data after anonymization
• Notify external systems or partners when a product goes out of stock or becomes available again
• Inform subscribed users, marketplaces, or marketing systems when a new product is added to the catalog

Why use webhooks over continuous polling

Continuous polling and webhooks are two approaches for receiving updates from a server. Continuous polling involves repeatedly checking the server for changes at regular intervals, which can be resource- and cost-intensive and may miss updates that occur between checks.

Compared to that, webhooks provide a more efficient solution by instantly notifying your application of updates by sending data to a specified URL as soon as an event occurs. This makes webhooks a more responsive and resource-efficient option for real-time updates.

Expectations for event data handling

Scope of Webhook Events

Webhook subscriptions for the Admin API are always global. Once subscribed to an event, the designated consumer endpoint will receive messages for all shop countries, including all relevant information about the triggering shop country.

Ordering event date

Events are not guaranteed to be sent, received, or processed in the right order. Although unlikely, it is possible that an order-canceled event could be sent before the order-confirmation event.

Blocking events

In cases of blocking events, it is only possible to register one subscription through the entire system, to be sure that the event is handled accordingly.

Activation of subscribed events

A new subscription is activated within 5 minutes, after which SCAYLE will start dispatching events.

Retry policy

When a webhook is triggered, a message is published to a queue. That message is then picked up by a worker, which sends a request to the provided remote host URL.
The message submission is only acknowledged when the consuming system response with a 2xx code. In case the response is different, the request will be resent until the response code is 2xx or the maximum retry count configured for the queue is reached. By default, we will retry 96 times, every 15 minutes (depending on the visibility timeout).

Handling duplicates

Duplicated webhook calls can happen if the first webhook call fails, the consuming system has not responded with a 2xx Status code, or the consuming system has not responded fast enough.
The consuming system is responsible for handling possible duplications, e.g. by validating event type and unique identifiers.

Manage webhooks

Subscribe to your first webhook

In the following section, you will learn how to create your first subscription by using webhook.site as a consumer application and the product-update event that we will trigger manually from within the SCAYLE Panel.

Let's get started! Within SCAYLE there are two ways how to subscribe to webhook events.

1. Use the SCAYLE Panel to create your subscription.
2. Create subscriptions through the Admin API.

Manage Webhooks in the SCAYLE Panel

Add a webhook

1. Go to Shops > Shop > Storefront > Checkout Settings > Admin Webhooks.
2. Click Add Webhook.
3. Fill in the Version field to keep track of your own versioning. (e.g. 1).
4. Add your target URL.
5. Select the Event you would like to subscribe to.
6. Click SAVE.

Manage Webhooks in the Admin API

Create an Admin API Token

• Go to Settings > General > API Keys.
• Click + Token under the Admin API Key section.
• (Optional) Add a comment and click Create Token
• Copy the displayed token.

Create a new webhook

Replace the URL with your generated webhook URL, then run the following code in a terminal.

cURL

Copy

echo '{
    "event": "product-update",
    "version": 1,
    "url": "https://webhook.site/eef2e8dc-****-****-cb8a-a544d9fd7044"
}' > createWebhook.json

curl -X POST -H "Content-Type: application/json" -H "X-Access-Token: YOUR-ADMIN-API-TOKEN-HERE" \
 -d @createWebhook.json \
    https://acme-live.admin.api.scayle.cloud/v1/webhooks/subscriptions

Response

After a successful subscription, you will receive the following response:

json

Copy

{
  "id": 42,
  "event": "product-update",
  "version": 1,
  "url": "https://webhook.site/eef2e8dc-****-****-cb8a-a544d9fd7044"
}

Test the subscription

1. Activate the webhook subscription: After initiating the subscription, wait for approximately 5 minutes to ensure it is fully active.
2. Save a product: Navigate to the SCAYLE Panel, make any necessary changes to a product, and save your changes.
3. Verify the information received: Check to see if the subscription has triggered and if the corresponding information has been sent to your defined endpoint as expected.

Best practices

Secure consumer endpoints

To ensure the security of your webhook consumer endpoints, implement Basic Authentication. This requires the webhook sender to provide a username and password with each request, which your endpoint will verify before processing the payload.

By using Basic Auth, you can prevent unauthorized access and ensure that only trusted sources can trigger your webhooks, adding an essential layer of security to your system.

Copy

https://MyUsername:[email protected]/notifiy

For more information about Basic Auth, visit MDN Web Docs.

Receiving webhook-calls and queuing

Queuing is an effective strategy for managing occasional bursts of traffic. By storing webhook payloads in a message queue, you can process them at a later time using your preferred queuing service. For SCAYLE webhook delivery, it’s crucial to send a quick, successful response to avoid unnecessary retry cycles and prevent delays in your consuming application.

Using a queue minimizes the risk of request timeouts and prevents webhook deliveries from being marked as failures. This approach allows your application to respond promptly while giving your processing tasks the flexibility to take the time they need, ensuring your system can handle a high volume of requests without issues.