INTEGRATION GUIDE

4. Calls your store makes to LeafOrder

4.1 Product-event webhook — POST — recommended

Send this whenever a product is created, updated or deleted in your store. LeafOrder then updates its product cache and automatically re-annotates the affected catalogs (new SKUs get linked, renamed/removed SKUs are cleaned up). Without webhooks, changes are picked up only by the next scheduled sync.

Required headers

Body (sign the exact bytes you send; don’t re-serialize after signing):

JSON

{
  "eventType": "product.updated",
  "productId": 1042,
  "sku": "BES.7170.03",
  "gtin": "8001234567890",
  "name": "Cordless drill 18V",
  "price": 119.90,
  "inStock": true,
  "imageUrl": "https://shop.example.com/media/1042.jpg",
  "description": "<p>18V brushless drill with two batteries.</p>"
}

Responses

Example (bash):

BASH

BODY='{"eventType":"product.created","productId":1042,"sku":"BES.7170.03","name":"Cordless drill 18V","price":129.90,"inStock":true}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -binary | base64)

curl -X POST https://platform.leaforder.com/api/app/webhook/product-event 
  -H "Content-Type: application/json" 
  -H "X-OrderPdf-Source: custom" 
  -H "X-OrderPdf-Signature: $SIG" 
  -H "X-OrderPdf-Timestamp: $(date +%s)" 
  -H "X-OrderPdf-Nonce: $(uuidgen)" 
  -d "$BODY"

Example (Node.js):

JS

import crypto from 'node:crypto';

async function sendProductEvent(event) {
  const body = JSON.stringify(event);                       // sign exactly what you send
  const signature = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
                          .update(body, 'utf8').digest('base64');
  const res = await fetch('https://platform.leaforder.com/api/app/webhook/product-event', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-OrderPdf-Source': 'custom',
      'X-OrderPdf-Signature': signature,
      'X-OrderPdf-Timestamp': String(Math.floor(Date.now() / 1000)),
      'X-OrderPdf-Nonce': crypto.randomUUID(),
    },
    body,
  });
  if (!res.ok) throw new Error(`order-pdf webhook failed: ${res.status}`);
}

Example (PHP):

PHP

$body = json_encode($event, JSON_UNESCAPED_SLASHES);
$sig  = base64_encode(hash_hmac('sha256', $body, $webhookSecret, true));
$ch = curl_init('https://platform.leaforder.com/api/app/webhook/product-event');
curl_setopt_array($ch, [
  CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'X-OrderPdf-Source: custom',
    'X-OrderPdf-Signature: ' . $sig,
    'X-OrderPdf-Timestamp: ' . time(),
    'X-OrderPdf-Nonce: ' . bin2hex(random_bytes(16)),
  ],
]);
curl_exec($ch);

Implementation tips: fire webhooks asynchronously (queue + retry with exponential back-off), debounce bursts (e.g. bulk imports – a scheduled sync is better for thousands of changes), and keep the sync endpoint authoritative.

4.2 Widget lookup — “is this product in a catalog, on which pages?” — GET

Used on product pages. Given the current product’s productId, it returns the catalogs (PDFs) containing it and the page numbers. Call it from the browser (the widget does this for you – see §5) or from your server.

HTTP

GET /api/widget/product-pdfs?connection=3b1f2a4e-5c6d-4e7f-8a9b-0c1d2e3f4a5b&product_id=1042 HTTP/1.1
Host: platform.leaforder.com
Origin: https://shop.example.com

Response 200:

JSON

{
  "pdfs": [
    {
      "fileName": "Spring 2026 Catalog",
      "fileKey": "tenants/…/annotated/spring-2026.pdf",
      "pages": [12, 13, 87],
      "thumbnailUrl": "https://…presigned-thumbnail-url…"
    }
  ]
}

• pdfs is an empty array when the product is not in any catalog, the product is unknown, or an internal error occurs → render nothing.
• pages are the 1-based page numbers where the product (or one of its family/variants) appears. Sorted ascending.
• fileKey is the opaque identifier you pass to the viewer component (§5). thumbnailUrl is a short-lived signed URL: don’t cache it.
• 400 { "error": "connection and product_id are required" } for missing/invalid parameters.
• The lookup is based on LeafOrder’s synced product cache, so the product must have been synced (or sent by webhook) first.

Server-side alternatives (use your secret key)

If you prefer to resolve everything on your server, both calls authenticate with the header X-OrderPdf-Key: {API_KEY} (the plain key is accepted; keep it on the server). Never call these from the browser.

By SKU – GET https://platform.leaforder.com/api/plugin/product-catalogs/{sku}

JSON

[ { "catalogId": "…guid…", "catalogName": "Spring 2026 Catalog",
    "viewToken": "…guid…", "pages": [12, 13, 87] } ]

Open the flipbook at https://platform.leaforder.com/view/{viewToken} (the first page can be passed to the viewer, see §5). 401 {"error":"Invalid or missing API key"} on bad key. An empty array means “not in any catalog”.

By productId (+ variants) – POST https://platform.leaforder.com/api/app/pdf-product-links/by-product

HTTP

POST /api/app/pdf-product-links/by-product HTTP/1.1
Host: platform.leaforder.com
X-OrderPdf-Key: 7f3c1d0e-8b2a-4a8e-9c55-2d6f1b7f0a11
Content-Type: application/json

{ "baseUrl": "https://shop.example.com", "productId": 1042, "associatedProductIds": [1043, 1044] }

associatedProductIds (optional) lets you include variants/children so a configurable product shows catalogs for any of its variants. Response shape: { "requestedProductId": 1042, "pdfs": [ { "pdfDocumentId", "fileName", "fileKey", "productId", "sku", "pages": [..], "thumbnailUrl" } ] }. 401 without the key header, an error for an invalid key.

Category pages – GET https://platform.leaforder.com/api/plugin/category-pdfs/{categoryId} (header X-OrderPdf-Key) returns the ready catalogs the merchant attached to a category ({ "pdfs": [ { "fileName", "fileKey", "thumbnailUrl", … } ] }), to show a catalog banner on category pages.