Webhooks​

Webhooks are a mechanism for apps to keep data synchronized with SHOPLINE stores or to perform actions when specific events occur in the store.

Webhooks provide a high-performance method for continuously polling for changes in store data.

When a specific event occurs in the store, such as an update to a store product, SHOPLINE immediately notifies your app server via an HTTP request. Your service can then update accordingly to keep data consistent.

Prerequisites​

To receive a webhook, the following conditions must be met:

• The store has installed your app.
• Your app has subscribed to a specific version of an event.

Subscribing to Events​

1. Complete the developer account app in the Developer Center.
2. Create an app.
3. Configure the events that need to be subscribed to.

Webhook payload format​

When there are changes to entities such as store orders or products, SHOPLINE will actively send a message to the configured event URL via an HTTP POST request.

Request Headers​

{
  "X-Shopline-Topic": "*****/****", // Event operation identifier
  "X-Shopline-Hmac-Sha256": "e.g. XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=", // Signature
  "X-Shopline-Shop-Domain": "e.g. shophub.myshopline.com", // Store domain
  "X-Shopline-Shop-Id": "e.g. 1610418123456", // Store ID
  "X-Shopline-Merchant-Id": "e.g. 2000001234", // Merchant ID
  "X-Shopline-API-Version": "e.g. v20210901", // Version number
  "X-Shopline-Webhook-Id": "e.g. b54557e48a5fbf7d70bcd043" // Message ID
}

Request Body​

See the event definition, such as [Order Update Event (/docsv2/ec20/2ff80e9159b517704ce43f0f74e6e247/i1vNgOUt).

Note that the version of the event you subscribe to in the Developer Center must match the webhook definition that your app service is using.

{
  "total_spent": "0",
  "addresses": [
    {
      "zip": "",
      "country": "",
      "address2": "",
      "city": "",
      "address1": "",
      "last_name": "",
      "province_code": "",
      "country_code": "",
      "default": true,
      "province": "",
      "phone": "",
      "company": "",
      "id": "SL201UA592875161232815849",
      "customer_id": "421475390",
      "first_name": ""
    }
  ],
  "gender": "others",
  "last_order_id": "1001",
  "created_at": "2023-05-10T17:00:01+08:00",
  "language": "en",
  "verified_email": false,
  "accepts_mobile_marketing": false,
  "accepts_marketing_updated_at": "2023-05-10T17:00:01+08:00",
  "orders_count": 1,
  "default_address": {
    "zip": "",
    "country": "",
    "address2": "",
    "city": "",
    "address1": "",
    "last_name": "",
    "province_code": "",
    "country_code": "",
    "default": true,
    "province": "",
    "phone": "",
    "company": "",
    "id": "SL201UA592875161228158749",
    "customer_id": "421453190",
    "first_name": ""
  },
  "updated_at": "2023-05-26T19:25:47+08:00",
  "accepts_marketing": true,
  "email_subscribe_flag": 1,
  "nick_name": "test1",
  "currency": "CLP",
  "id": "421475190",
  "state": 3,
  "first_name": "test1",
  "email": "test1@joyy.com",
  "mobile_subscribe_flag": 2
}

Event notification protocol​

1. SHOPLINE sends events using the POST method, with the business data in the request body. Content-Type: app/json.
2. Each event notification requires an acknowledgment (ack) response. The subscriber must respond in the specified format to inform SHOPLINE of successful processing. Otherwise, SHOPLINE considers the notification as failed and initiates a retry.

Successful response example

HTTP/1.1 200 OK

3. Retry Policy

• If no response is received 5 seconds after the initial notification, SHOPLINE considers the notification as failed and starts the retry process.
• If no response is received, SHOPLINE will make 19 retries within 48 hours. If a specific event message fails to be successfully processed for 19 consecutive retry attempts and there are no other successful records of the same type of message during the retry phase, the platform will remove the subscription record of the app and send an email titled "Webhook Event Subscription Deletion."
• Starting from the first attempt, the interval between each retry is as follows: 0 seconds, 5 seconds, 10 seconds, 30 seconds, 45 seconds, 1 minute, 2 minutes, 5 minutes, 12 minutes, 38 minutes, 1 hour, 2 hours, 4 hours, 4 hours, 4 hours, 4 hours, 4 hours, 4 hours, 4 hours.

4. SHOPLINE event notifications do not guarantee that they will not be duplicated. The subscriber must be able to handle duplicate notifications correctly. If a notification has already been processed, the subscriber should simply return a successful response.
5. Ensuring platform stability and deliverability of notifications is the platform's responsibility. Event notifications cannot guarantee a 100% success rate, so it is recommended that the subscriber actively engage in compensatory interface integration to ensure correct processing of platform data.

Signature Verification​

• Signature Algorithm: hmacSha256
• Content to be signed: Request Body
• Signature Algorithm Example (Java version):

/**
     * hmacSha256 
     * @param source signContent
     * @param secret appSecret
     * @return
     */
    public static String hmacSha256(String source, String secret) {
        if (StringUtils.isEmpty(secret) || StringUtils.isEmpty(source)) {
            return null;
        }
        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            sha256_HMAC.init(secret_key);
            byte[] bytes = sha256_HMAC.doFinal(source.getBytes(StandardCharsets.UTF_8));
            return new String(Hex.encodeHex(bytes));
        } catch (Exception e) {
            e.printStackTrace();
            return null;
        }
    }