Webhook

Webhooks provide a powerful method for app developers take actions when specific events occured.

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.

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.

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

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.