Skip to main content

Webhook Overview

Webhooks allow your app to passively receive store events — when an order is created, a product is updated, or an app is uninstalled, Shoplazza actively POSTs the event payload to the URL you registered in advance.

Want to check the event list directly? Go to Webhook Events.

Webhook vs Polling​

PollingWebhook
Data flowApp → Shoplazza (pull)Shoplazza → App (push)
Real-timeDepends on polling intervalSeconds
Resource consumptionHigh (frequent requests + mostly empty responses)Low (called only when events occur)
API quotaConsumedNot consumed

For scenarios that require real-time responses to business events (e.g., order fulfillment, inventory sync, uninstall cleanup), Webhook is always the preferred choice.

Subscription Lifecycle​

① Your app calls POST /openapi/.../webhooks to register a subscription
        │
        ▼
② Shoplazza persists the subscription (topic, address)
        │
        ▼
③ Event triggers → Shoplazza POSTs payload to your address
        │
        ▼
④ Your app verifies the signature → processes business logic → returns 2xx
        │
        ▼
   ⓧ Non-2xx response or timeout → enters retry queue (see below)

Complete CRUD API: Webhook API.

Register a Subscription​

POST https://<shop>/openapi/2022-01/webhooks
Access-Token: <access_token>
Content-Type: application/json

{
    "topic": "products/create",
    "address": "https://your-app.example.com/webhook/products-create",
}
  • topic: Event identifier. See the complete list in Webhook Events
  • address: URL that receives the POST request. Must be HTTPS

Verify the Signature​

After receiving a POST request delivered by Shoplazza, your app must verify the signature before trusting the payload.

Each webhook request includes a base64-encoded X-Shoplazza-Hmac-Sha256 header, which is generated by performing HMAC-SHA256 on the raw request body using your app's Client Secret, then base64-encoding the result. To verify, compute the same algorithm and compare it with the header using a time-safe comparison. If they match, the payload can be trusted. Perform this verification before your app responds to the webhook.

Note the difference from OAuth callback (Scenario 1): Webhook signs the raw body and outputs base64; OAuth signs the sorted query string and outputs hex.

For algorithm steps and multi-language code examples (Ruby, Node.js), see HMAC Signature Verification · Scenario 2.