About webhooks

Webhooks provide a powerful method for app developers take actions when specific events occured. When your app needs information about specific events that have occurred on a shop, it can subscribe to Shoplazza webhook topics as a mechanism for receiving near-real-time data about these events.

Shoplazza webhooks are useful for keeping your app in sync with Shoplazza data, or as a trigger to perform an additional action after that event has occurred. They are also a performant alternative to continuously polling for changes to a shop's data.

Examples of when your app might use webhooks

• Anchor link to section titled "Examples of when your app might use webhooks"
• Sending notifications about changes in inventory levels to inventory management clients and pagers
• Informing shipping companies about changes in orders, returns, or refunds
• Removing customer data from a database for app uninstalls
• Integrating data about orders with accounting software
• Updating a product's warranty price based on changes to the product's price

Versioning

The event object sent in a webhook is dictated by the webhook api version, if your app is set to a webhook api version, such as 2020-01, then update to 2020-07, the event object generated and sent to your endpoint is based upon the 2020-07 version. The webhook api version option can be found when create Private APP on store admin or create app on partner center.

WorkFlow

1. The app subscribes to the orders/create topic for a shop and listens for order creation events.
2. The app specifies an endpoint to receive webhooks for the orders/create topic. For example, this may be an HTTPS endpoint hosted by the app server. This endpoint is where the app listens for webhooks.
3. Suppose now that an order is created from that shop.
4. This triggers a webhook to be published to the orders/create topic.
5. Shoplazza sends that webhook, which includes headers and an order payload, to the specified subscription endpoint.

Events

Shoplazza Supported Webhook Events .

You can receive differnet events by create webhook subscription with endpoints url, please pay attention to the following points:

• You can only create webhook when app is granted certain access scope. For example, if the APP withought read_order permission, create orders/update webhook will return failure.
• Listen extra events is not recommended, it just waste your server resource.

Shoplazza Webhook Key Features

Ordering event data

As with other webhook systems, Shoplazza doesn't guarantee ordering within a topic, or across different topics for the same resource. For example, it's possible that a products/update webhook might be delivered before a products/create webhook.

Based on this, you cannot rely on Webhooks for some reliable business processing; if needed, it is best to do so through the API method.

Delivery attempts and retries

If call you endpoints url response not 2xx http status code, Shoplazza attemtps to deliver webhooks 19 times for up to two days with an exponential back off. Example of time intervals, 1 minute, 2 minute, 2 minute, 5 minute, 20 minute, 30 minute, 1 hour, 2 hour, 4hour * 11.
The webhook will be deleted if always deliver failed, you should create webhook again.

Signature Payload

Verify webhook signatures to confirm that received events are sent from Shoplazza, you can refer to the document chapter verify a webhook.

Each request sent by Shoplazza to a third party is accompanied by an HMAC signature.

Verify a webhook

The HMAC verification process for OAuth is different from the process to verify webhooks.

Webhooks can be verified by calculating a digital signature. Each webhook request include a base64 encoded X-Shoplazza-Hmac-Sha256 header, which is generated using the app's Client Secret along with the data sent in the request.

To verify that the request came from Shoplazza, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Shoplazza-Hmac-Sha256 header. If they match, then you can be sure that the webhook was sent from Shoplazza. As a best practice, the HMAC digest should be verified before the app responds to the webhook.

The following example use Ruby and Sinatra to verify a webhook request:

require 'rubygems'
require 'base64'
require 'openssl'
require 'sinatra'

# Shoplazza's Client Secret
SECRET = 'my_secret'

helpers do
  # Compare the computed HMAC digest based on the shared secret and the request contents to the reported HMAC in the headers
  def verify_webhook(data, hmac_header)
    calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest('sha256', SECRET, data))
    ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, hmac_header)
  end
end

# Responds to the HTTP POST request
post '/' do
  request.body.rewind
  data = request.body.read
  verified = verify_webhook(data, env["X-Shoplazza-Hmac-Sha256"])

  puts "Webhook verified: #{verified}"
end

const crypto = require("crypto");
# Shoplazza's Client Secret
const CLIENT_SECRET = 'my_secret';

function webhookValidatorMiddleWare(req, res, next) {
  const signature = req.headers['x-shoplazza-hmac-sha256'];    
  const data = JSON.stringify(req.body);
    const expectedSignature = crypto
      .createHmac('sha256', CLIENT_SECRET) // app secret
      .update(data)
      .digest();

    const signatureBuffer = Buffer.from(signature, 'base64');

    if (
      signatureBuffer.length !== expectedSignature.length ||
      !crypto.timingSafeEqual(signatureBuffer, expectedSignature)
    ) {
      return res.status(403).json({ error: '无效签名' });
    }

    next()
} 

Handle duplicate events

Although we try to avoid duplicate sending events, you still may receive the same event more than once. We advise you to process events idempotent. You can log the events you’ve processed, and never to process it again.

Polling data via openapi

Receiving data from webhooks is not always reliable, to avoid missing proccessing events, you can build a job to poll data via our openapi. Most openapi support both the created_at_min and updated_at_min filter parameters, so you can poll data since the last time the job ran.

Whitelist

If your server restricts IP requests, please add Shoplazza's external IP 34.210.253.121 / 52.11.173.113 to the whitelist.