Storefront app proxy

​

How a request flows

1. A shopper opens https://shop.example.com/apps/reviews/stars?product=123.
2. Salesive finds the active installation of the app whose slug is reviews on that store.
3. It builds https://apps.example.com/reviews/stars?product=123 from the app’s proxyUrl (https://apps.example.com/reviews), the rest of the path and the query string, and sends a GET to it.
4. Your app answers. Salesive passes the status, the content type and the body back to the shopper.

​

Set the proxy URL

curl -X PUT https://api.salesive.com/api/v1/apps/developer/<appId> \
  -H "Authorization: Bearer <your-merchant-session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "proxyUrl": "https://apps.example.com/reviews" }'

• The base path is kept. https://apps.example.com/reviews plus /stars becomes https://apps.example.com/reviews/stars.
• A query string already on the proxy URL is kept, and the incoming query is appended after it.
• Send "" or null to remove it.
• The URL must be HTTPS, must not contain credentials, and must not resolve to a private, loopback or link local address. Salesive checks it with the same guard as a webhook URL when you save it.
• One URL serves every install, unless a release pins a different one.

​

Releases and development installs

​

What your app receives

​

Methods

​

URL

​

Headers

​

Body

​

Verify the signature

• Verify the raw bytes before parsing.
• Reject a t more than 300 seconds from your clock, in either direction.
• A GET has an empty body, so the signed string is <t>. followed by nothing.

import express from "express";
import crypto from "crypto";

const app = express();
const SIGNING_SECRET = process.env.SALESIVE_WEBHOOK_SECRET; // whsec_...
const TOLERANCE_SECONDS = 300;

const safeEqual = (a, b) => {
  const left = Buffer.from(a);
  const right = Buffer.from(b);
  return left.length === right.length && crypto.timingSafeEqual(left, right);
};

// Buffer every content type raw, because the signature covers the bytes.
app.use("/apps", express.raw({ type: () => true }));

app.use("/apps", (req, res) => {
  const parts = Object.fromEntries(
    (req.get("X-Salesive-Signature") || "")
      .split(",")
      .map((part) => part.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1 || "";

  if (
    !Number.isFinite(timestamp) ||
    Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS
  ) {
    return res.status(401).send("stale signature");
  }

  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(`${timestamp}.`)
    .update(req.body || Buffer.alloc(0))
    .digest("base64");

  if (!safeEqual(signature, expected)) {
    return res.status(401).send("invalid signature");
  }

  const shopId = req.get("X-Salesive-Shop");
  const appSlug = req.get("X-Salesive-App");
  // ... handle the request
});

​

What your app returns

• The status code and the Content-Type pass through. The body is not rewritten. If your app sends no content type, the response is application/octet-stream.
• Only Content-Type is taken from your response headers. Your app cannot set cookies or custom headers on the storefront response.
• Every response, including errors, is Cache-Control: private, no-store and X-Content-Type-Options: nosniff.
• A 3xx is refused. Salesive answers 502 rather than following a redirect the shopper never sees.
• A response over 5 MB is 502.
• Your app has 10 seconds to answer, body included. A timeout is 504.
• An unreachable app is 502.

​

Limits and errors

​

Uninstall and suspend

​

Security notes

• The request comes from Salesive’s storefront servers, not from the shopper’s browser. Your endpoint must be reachable from the public internet over HTTPS.
• The signed headers are the only trusted identity. Your endpoint is also reachable outside the proxy, so never trust a header a caller could set itself.
• The proxy carries no app token and no scopes. If you need store data, call the Apps API with your own app token, the same as any other request.
• Treat the path, query and body as untrusted shopper input.

​

Next steps