Overview

A webhook is an event-driven message delivery mechanism, which can be used to keep app data in sync with SHOPLINE store data or to trigger specific actions when certain store events occur. Compared to continuous polling, webhooks provide a more efficient, low-latency method for receiving updates to store data.

When a specific store event occurs (such as a product update), SHOPLINE instantly sends an HTTP request to your app server. Your server can then process this request to update data promptly, keeping your app data aligned with SHOPLINE.

Prerequisites​

To ensure your app receives webhook notifications, make sure that the following requirements are met:

• Your app is installed on the target store.
• Your app is subscribed to the target events for the corresponding API version.

Event subscription​

Perform the following steps to subscribe to an event:

1. Go to the Partner Portal to sign up for a developer account.
2. Create an app.
3. Call the Subscribe to a Webhook API to subscribe to the target event.

Webhook request format​

When a subscribed event occurs within a SHOPLINE store (such as changes to orders, products, or other entities), SHOPLINE proactively sends an HTTP POST request to the endpoint specified for the subscription.

Request headers​

Example:

{
  "X-Shopline-Topic":"orders/edited",//The unique identifier for the event.
  "X-Shopline-Hmac-Sha256":"XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=",//The signature of the request.
  "X-Shopline-Shop-Domain":"yourhandle.myshopline.com",//The store domain.
  "X-Shopline-Shop-Id":"*******123456",//The store ID.
  "X-Shopline-Merchant-Id":"*******234",//The merchant ID.
  "X-Shopline-API-Version":"v20260901",//The API version.
  "X-Shopline-Webhook-Id":"b54557e48a5fbf7d70bcd043" //The ID of this webhook event.
}

Request body​

The content of the request body depends on the event definition. The example below shows the payload format for a customer created event.

Example:

{
  "total_spent":"0",
  "addresses":[
    {
      "zip":"",
      "country":"",
      "address2":"",
      "city":"",
      "address1":"",
      "last_name":"",
      "province_code":"",
      "country_code":"",
      "default":true,
      "province":"",
      "phone":"",
      "company":"",
      "id":"SL201UA592875161232815849",
      "customer_id":"******390",
      "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":"******390",
    "first_name":""
  },
  "updated_at":"2023-05-26T19:25:47+08:00",
  "accepts_marketing":true,
  "email_subscribe_flag":1,
  "nick_name":"test1",
  "currency":"CLP",
  "id":"******390",
  "state":3,
  "first_name":"test1",
  "email":"****@example.com",
  "mobile_subscribe_flag":2
}

Event delivery and retry policy​

To ensure real-time event notifications, SHOPLINE implements a standard delivery mechanism and a retry policy for failures.

Delivery and response mechanism​

SHOPLINE delivers events via HTTP POST requests with the Content-Type header set to application/json, carrying the event data in JSON format within the request body. Once an event is sent, your app must respond within 5 seconds in the format shown below to acknowledge a successful delivery. Otherwise, SHOPLINE will consider the delivery a failure and trigger the retry mechanism.

Sample success response:

HTTP/1.1 200 OK

Retry policy​

When an event delivery is considered a failure, SHOPLINE triggers an automatic retry mechanism. The system will attempt a maximum of 19 retries within 48 hours following the initial failure. The interval between each consecutive retry increases progressively: 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, and 4 hours.

If an event delivery fails all 19 retry attempts and no other successful deliveries of the same event type are recorded during this retry period, SHOPLINE will automatically cancel your app's subscription to that event and send you an email with the subject line "Webhook Event Subscription Deleted".

Considerations​

When using webhooks, take note of the following items:

• Webhook event delivery is not guaranteed to be 100% reliable. To ensure the eventual consistency of your business data, we recommend integrating corresponding query APIs into your app. For example, alongside subscribing to the order created event, your app can call the Get orders API to proactively verify order statuses.
• Once an event subscription is canceled, SHOPLINE will immediately stop all message delivery for that event. To resume receiving notifications, you must recreate the event subscription.

Signature verification​

To ensure the authenticity and security of webhook messages, we recommend that your app perform signature verification upon receiving an event delivery. For more details, refer to Generate and verify signatures.

• Signing algorithm: HMAC-SHA256
• Content to verify: The raw request body string
• Signing key: The app secret