Webhook best practices

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.

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.