Webhooks

Subscribe HTTPS endpoints to shop events. Signing secrets are shown once at creation. Manage endpoints in Admin → Settings → API credentials.

Events

order.created, order.updated, order.paid, order.cancelled, order.refunded, product.created, product.updated, product.deleted, customer.created, customer.updated.

Example delivery

Each delivery is a POST with JSON body and signature header.

POST /your-webhook-endpoint HTTP/1.1
Host: example.com
Content-Type: application/json
X-Webhook-Signature: sha256=3f1a…

{
  "id": "evt_01HXYZ...",
  "topic": "order.created",
  "shopId": "shop_01HXYZ...",
  "createdAt": "2026-10-08T12:00:00.000Z",
  "data": {
    "orderId": "ord_01HXYZ...",
    "orderNumber": "10042"
  }
}

Verify signatures

Compute HMAC-SHA256 of the raw body with your endpoint secret and compare to X-Webhook-Signature.

import crypto from "node:crypto";

function verifyRetailLinkWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const provided = String(signatureHeader || "")
    .replace(/^sha256=/, "");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(provided)
  );
}

// Header: X-Webhook-Signature: sha256=<hex>

Delivery

Deliveries are queued and sent asynchronously. Your endpoint should respond quickly with 2xx; treat duplicate deliveries as idempotent using the event id.