docs(shopline): signature is lowercase hex, not base64 — verified against a live delivery (#150)

SHOPLINE's docs show a base64 digest in the header example and a code sample
showing hex; the brief told readers to assume base64. A live products/create
delivery (api_version v20240601) settles it the other way: the header was 64
lowercase hex characters and matched a recomputed HMAC-SHA256 over the raw
body with the app secret exactly.

Handlers still accept both encodings, since the documented example disagrees
with observed behaviour, but hex is now documented as what to expect.

Also captured from the same delivery: api_version is required in the
webhook-creation body (400 without it) and is echoed back in
X-Shopline-Api-Version.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: garethx

providers.yaml

@@ -1928,13 +1928,18 @@ providers:
       E-commerce platform. The SHOPLINE Open Platform (developer.shopline.com, English) is a
       Shopify clone. Webhooks are signed with HMAC-SHA256 of the RAW request body keyed by the
       app secret (Developer Center > App credentials); the signature is in the
-      X-Shopline-Hmac-Sha256 header. Encoding is base64 (the docs' header example is base64,
-      Shopify-style — though a stray code sample shows hex; treat as base64 and fall back to hex
-      if needed). Constant-time compare against the raw un-parsed body. This is NOT the Standard
+      X-Shopline-Hmac-Sha256 header. *** ENCODING VERIFIED (Jul 2026, live products/create
+      delivery on api_version v20240601): the digest is LOWERCASE HEX, 64 chars — confirmed by
+      recomputing HMAC-SHA256 over the raw body with the app secret and matching the header
+      exactly. The docs' header example shows base64 (Shopify-style) and is MISLEADING; the
+      "stray" hex code sample is the correct one. Handlers may accept both as a safety net, but
+      expect hex. *** Constant-time compare against the raw un-parsed body. This is NOT the Standard
       Webhooks spec. Other headers: X-Shopline-Topic, X-Shopline-Shop-Domain, X-Shopline-Shop-Id,
       X-Shopline-Merchant-Id, X-Shopline-API-Version, X-Shopline-Webhook-Id (stable across resends,
       use for idempotency). Topics use Shopify-style slash format (orders/create, products/update,
-      collect/delete). Subscribe via the Admin REST API
+      collect/delete). NOTE: api_version is REQUIRED in the webhook-creation body — omitting it
+      returns 400 "The required property 'api_version' is missing from the object"; deliveries echo
+      it back in X-Shopline-Api-Version. Subscribe via the Admin REST API
       POST https://{handle}.myshopline.com/admin/openapi/{version}/webhooks.json with
       {topic, address, api_version}. Gotchas: 5s response timeout; up to 19 retries over 48h then
       the subscription is auto-removed. No official published SDK — verify manually.

skills/shopline-webhooks/SKILL.md

@@ -28,11 +28,18 @@ secret** (Developer Center → App credentials) and sends the digest in the
 `X-Shopline-Hmac-Sha256` header. Use the **raw** body — parsing JSON first
 changes the bytes and breaks the signature — and compare timing-safe.
 
-> **Encoding:** SHOPLINE's docs show a **base64** digest (Shopify-style), but a
-> stray code sample shows **hex**. To be safe, accept either: compute both and
-> timing-safe compare against each. Then **confirm which encoding your real
-> deliveries use** — log one live `X-Shopline-Hmac-Sha256` value (44 chars ending
-> in `=` is base64; 64 `[a-f0-9]` chars is hex) — and you can narrow the check.
+> **Encoding — verified as lowercase hex.** SHOPLINE's docs show a **base64**
+> digest in the header example (Shopify-style), while a code sample shows **hex**.
+> A live delivery settles it: the code sample is right. Confirmed against a real
+> `products/create` webhook (API version `v20240601`) by recomputing
+> HMAC-SHA256 over the raw body with the app secret — the header was 64 lowercase
+> hex characters and matched exactly.
+>
+> The handlers below still accept either encoding, since the documented example
+> disagrees with observed behaviour and SHOPLINE could differ by version or
+> region — but expect hex. To check your own: 64 `[a-f0-9]` chars is hex; 44
+> chars ending `=` is base64.
+>
 > The topic is in `X-Shopline-Topic`; the shop domain in `X-Shopline-Shop-Domain`.
 
 Node:
@@ -43,8 +50,8 @@ const crypto = require('crypto');
 function verifyShoplineWebhook(rawBody, hmacHeader, secret) {
   if (!hmacHeader) return false;
   const digest = crypto.createHmac('sha256', secret).update(rawBody).digest();
-  // Accept base64 (documented) or hex (stray sample) — timing-safe either way.
-  return [digest.toString('base64'), digest.toString('hex')].some((expected) => {
+  // Verified hex in practice; base64 kept as a fallback. Timing-safe either way.
+  return [digest.toString('hex'), digest.toString('base64')].some((expected) => {
     try {
       return crypto.timingSafeEqual(Buffer.from(hmacHeader), Buffer.from(expected));
     } catch {
@@ -63,7 +70,7 @@ def verify_shopline_webhook(raw_body: bytes, hmac_header: str, secret: str) -> b
     if not hmac_header:
         return False
     digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()
-    # Accept base64 (documented) or hex (stray sample).
+    # Verified hex in practice; base64 kept as a fallback.
     return (
         hmac.compare_digest(hmac_header, base64.b64encode(digest).decode())
         or hmac.compare_digest(hmac_header, digest.hex())

skills/shopline-webhooks/references/setup.md

@@ -43,6 +43,10 @@ curl -X POST \
   }'
 ```
 
+> **`api_version` is required in the create body.** Omitting it returns
+> `400 body.webhook:The required property 'api_version' is missing from the object`.
+> Deliveries then echo it back in the `X-Shopline-Api-Version` header.
+
 Repeat for each topic you want (`orders/create`, `products/update`,
 `collect/delete`, etc.). See
 [Subscribe to a Webhook](https://developer.shopline.com/docs/apps/api-instructions-for-use/webhooks/overview/)