Webhooks - Salesive Docs

Overview

Instead of polling, your app can receive webhooks — Salesive sends an HTTP POST to your endpoint whenever something changes on a store your app is installed on (an order is created, a product updated, and so on).

A webhook is a notification, not the data. A delivery tells you what changed — the resource, the action, and the affected record’s id — but it does not include the record’s fields. Fetch the current state yourself from the Apps API with your app token (see Fetch the current data). Reading it back through your own scoped token means you only ever receive data your permissions allow, and you always act on the latest state rather than a possibly-stale snapshot.

Webhooks are permission-gated: you only receive events for a resource if the merchant granted your app the scope that governs it (e.g. you get orders/* events only if the installation has READ_ORDERS). See Scopes & permissions.

Enable webhooks

Set a Webhook URL on your app in the dashboard Developer console (it’s optional; leave it blank to disable). When you save it, the console shows your app’s signing secret (whsec_…), which you use to verify deliveries. The URL must pass the same guard Salesive applies on every delivery:

HTTPS only. Plain http is refused.
No credentials in the URL (user:password@host).
No private destinations. The hostname must resolve only to public addresses. Loopback, private, link local, carrier grade NAT, multicast, documentation, benchmarking and reserved ranges are refused for IPv4 and IPv6, and localhost is refused by name.
No redirects. A 3xx answer is a failed delivery, not a second request to a destination the guard never checked.

The URL is checked when you save it and again before every attempt, and the connection is pinned to an address that passed the check so DNS cannot rebind between the two. A save that fails the guard returns 400 with the reason.

One webhook URL serves all installations of your app, unless you publish releases that pin different installs to different snapshots. Each delivery tells you which store it’s for (shopId in the body and the X-Salesive-Shop-Id header), so route by that.

Choose the topics you receive

By default an app receives every topic its scopes allow. Set webhookTopics on your app (the field accepted by PUT /api/v1/apps/developer/:id) to a list such as ["orders/created", "orders/fulfilled", "inventory/updated"] to receive only those. An empty or missing list means every topic. Each entry is lowercase resource/action (letters, digits, _ and -), and the list holds at most 100 topics; anything else is a 400. Five topics cannot be opted out of, because they are lifecycle or legal notices rather than feature events: app/uninstalled, app/test, customers/redact, shop/redact and customers/data_request. They are delivered even when they are not in webhookTopics. See Data protection.

webhookTopics is part of a release snapshot. If you publish releases, changing the list on the app does not reach installs pinned to an older release until you publish a new one.

Payload shape

Every delivery is a POST with a JSON body, and every topic uses the same notify-only envelope:

{
  "id": "8f1c2e3a-6b7d-4c1a-9e2f-9b0d",
  "topic": "orders/updated",
  "resource": "orders",
  "action": "updated",
  "resourceId": "66b1f0a3c2d4e5f6a7b8c9d0",
  "shopId": "6680aabbccddeeff00112200",
  "actorInstallationId": "66f1bbccddeeff00112233445",
  "occurredAt": "2026-06-28T18:42:11.000Z"
}

The body carries no record fields. A webhook body is never the record itself, and no body is ever stored: the delivery log keeps the topic, ids, status and timing only. When an event arrives, re-fetch the record from the API with your own scoped token (see Fetch the current data).

Field	Description
`id`	Unique delivery id. Use it to dedupe — retries reuse the same id.
`topic`	`resource/action` (see below). The `action` is best-effort.
`resource` / `action`	Resource changed, and one of `created` / `updated` / `deleted`.
`resourceId`	The affected record’s id — present on creates (the new record), updates and deletes. May be absent for bulk/sub-actions; when it is, re-list the affected `resource`.
`shopId`	The store this event belongs to.
`actorInstallationId`	Present only when the write came from an app token: the installation id of the app that made it. Compare it with your own installation id to recognize your own writes, and skip them so your app never reacts to its own echo. Absent on merchant, staff and storefront writes. Delivery is unchanged either way: you still receive every event you are subscribed to, including your own.
`occurredAt`	ISO-8601 timestamp.

Per-topic additions

A few topics add a small, fixed field on top of the envelope. Nothing else is ever added, and no topic ever carries the record itself.

Topic family	Added field	Exact shape
Storefront cart and order events	`customerId`	A string: the shopper’s user id. Added to `carts/*`, `orders/placed` and `orders/paid`. On cart events it repeats `resourceId`; on order events `resourceId` is the order id, so this is the only shopper id in the body. Never added to admin events, where the actor is a staff member, not a shopper.
`carts/*` when the install holds `READ_CART_CONTENTS`	`cart`	`{ "itemCount": 3, "totalPrice": 12500 }`. `itemCount` sums line quantities. `totalPrice` is in major units and is omitted when the cart has no numeric total. The aggregate only, never the line items.
`orders/placed`	`sourceCartId`	A string: the id of the cart the order was created from, when the order records one. Use it to match the order to the cart you were recovering.
Billing topics caused by a payment	`chargeId`	A string: the charge id. Present on `subscriptions/activated`, `subscriptions/renewed` and `charges/refunded` when a payment produced the event. `charges/refunded` also adds `refundId`, a string.
`domains/dns_verified`	`requestId` and `record`	`requestId` is the DNS request id, a string. `record` is `{ "host": "send", "type": "txt", "value": "v=spf1 include:_spf.example.com ~all" }`.

The cart aggregate is computed per installation from the scopes that installation holds. Two apps on the same store can therefore receive the same event with different bodies, each signed with its own secret. An install without READ_CART_CONTENTS receives the envelope without cart.

Example: a cart event with the aggregate

This install holds both READ_CARTS (so it receives the event) and READ_CART_CONTENTS (so the body carries the cart aggregate):

{
  "id": "8f1c2e3a-6b7d-4c1a-9e2f-9b0d",
  "topic": "carts/item_added",
  "resource": "carts",
  "action": "item_added",
  "resourceId": "66b1f0a3c2d4e5f6a7b8c9d0",
  "shopId": "6680aabbccddeeff00112200",
  "occurredAt": "2026-11-08T12:30:00.000Z",
  "customerId": "66b1f0a3c2d4e5f6a7b8c9d0",
  "cart": {
    "itemCount": 3,
    "totalPrice": 12500
  }
}

To read the line items, call GET /carts/66b1f0a3c2d4e5f6a7b8c9d0 with your app token. See Carts.

Headers

Header	Value
`X-Salesive-Topic`	The event topic, e.g. `orders/updated`.
`X-Salesive-Shop-Id`	The store id.
`X-Salesive-App-Client-Id`	Your app’s `clientId`.
`X-Salesive-Event-Id`	Same as the body `id`.
`X-Salesive-Signature`	`t=<unix seconds>,v1=<signature>` for the current signature scheme (see below).
`X-Salesive-Hmac-SHA256`	The older signature: base64 HMAC-SHA256 of the raw body. Still sent, and still valid.

Topics

topic is resource/action. For admin events the action is created (POST), updated (PUT/PATCH), or deleted (DELETE). Storefront events (customer activity on the live store) carry their own action (signed_in, placed, paid, and so on). You receive a topic only if your installation holds the scope below, except the mandatory lifecycle and data protection topics, which are always delivered.

Admin events (dashboard / API changes)

Resource	Required scope	Example topics
`orders`	`READ_ORDERS`	`orders/created`, `orders/updated`, `orders/cancelled`
`shop`	`READ_SETTINGS`	`shop/updated`
`products` / `foods` / `services`	`READ_INVENTORY`	`products/updated`, `foods/created`
`digital-products` / `digital-access`	`READ_INVENTORY`	`digital-products/created`, `digital-access/created`
`categories`	`READ_CATEGORIES`	`categories/created`
`customers`	`READ_CUSTOMERS`	`customers/updated`
`shipping`	`READ_SHIPPING`	`shipping/created`
`discounts`	`READ_DISCOUNTS`	`discounts/created`
`blogs`	`READ_BLOGS`	`blogs/updated`
`notifications`	`READ_NOTIFICATIONS`	`notifications/updated`
`tasks`	`READ_TASKS`	`tasks/created`
`notes`	`READ_NOTES`	`notes/updated`
`scripts`	`READ_SCRIPTS`	`scripts/created`
`comments`	`WRITE_COMMENTS`	`comments/created`
`shipday`	`READ_SHIPDAY`	`shipday/updated`
`kyc`	`READ_KYC`	`kyc/updated`
`domains`	`READ_DOMAINS`	`domains/updated`
`roles`	`READ_ROLES`	`roles/updated`
`payouts`	`READ_PAYOUTS`	`payouts/updated`
`files`	`READ_FILES`	`files/created`, `files/updated`, `files/deleted`
`settings`	`READ_SETTINGS`	`settings/updated`
`metafields` / `metafield-definitions`	`READ_METAFIELDS`	`metafields/created`, `metafields/updated`, `metafield-definitions/deleted`

Digital stores. The action comes from the HTTP method, so some sub-actions do not read naturally: granting, extending or revoking buyer access (all POST) arrive as digital-access/created, and so does a bulk delete of products (digital-products/created). Saving the all-access pass is digital-products/updated with no resourceId. Re-fetch with List buyer access or Get the all-access pass to see what changed. Access that is granted automatically when a buyer pays is not published as a digital-access event.

Metafields. Each delivery covers one metafield, so a batch write arrives as one delivery per row, and the body adds metafield: { ownerType, ownerId, namespace, key }. Changes in an app’s own namespace go to that app only. See Metafields.

shop/updated fires when the merchant changes the store profile, business details, location, app info or published website config. resourceId is the store id and a section field says which part changed (profile, business, location, app, website_config); read the values from GET /app/context, which every installed app can call. It rides READ_SETTINGS rather than a scope of its own because the profile is already readable without a scope. Changes to store settings keep their own settings/updated topic; the two are never sent for the same change.

Order, stock and lifecycle events

These describe what happened rather than which route was called, so they fire however the change was made: the dashboard, another app, Ola, or a payment.

Topic	Required scope	When it fires
`orders/fulfilled`	`READ_ORDERS`	An order’s status moves to `completed`.
`orders/refunded`	`READ_ORDERS`	An order’s status moves to `refunded`. A record: Salesive moves no money.
`inventory/updated`	`READ_INVENTORY`	A product’s stock changes: an edit, a bulk quantity change, a POS sale, a seller marking an order paid, or a storefront payment. One event per product; `resourceId` is the product id, fetch it with `GET /products/{id}`. Foods, services and digital items have no stock and never send it.
`app/uninstalled`	none	The merchant uninstalled your app. Sent once, to your app only, at the webhook URL and with the secret of the environment the install used (development installs get the development pair). `resourceId` is the installation id. Your tokens are already revoked, so do not call the API; clean up your side.
`app/test`	none	A synthetic test event sent from the developer console or `POST /api/v1/apps/developer/:id/webhook-test`. It carries `test: true`, the installation id as `resourceId` and no store record. Use it to check connectivity and signature verification.

A status change sends orders/fulfilled or orders/refunded once: saving an order that is already refunded again sends nothing. The route that made the change still sends its own orders/updated.

Data protection topics

These are legal notices, not feature events. They cannot be opted out of: they ignore webhookTopics and are sent to every active installation of the shop that has a webhook URL. What to do when one arrives, and the 30 day expectation, is in Data protection.

Topic	Required scope	When it fires
`customers/redact`	none	A customer record was deleted from the store. `resourceId` is the customer id.
`customers/data_request`	`READ_CUSTOMERS`, `WRITE_CUSTOMERS` or `READ_CUSTOMER_ANALYTICS`	The merchant asked for a copy of what the store holds for one customer. `resourceId` is the customer id.
`shop/redact`	none	The store was deleted, or its owner deleted their account and the store was taken offline. `resourceId` is the shop id.

The customer topics carry the customer id in resourceId; shop/redact is shop wide and uses the shop id. None of them carry the customer’s fields.

Storefront events (live shopper activity)

These fire from the storefront when a shopper acts on the live store.

Topic	Required scope	When it fires
`customers/signed_in`	`READ_CUSTOMERS`	A shopper completes authentication (email OTP verified — new or returning). `resourceId` is the shopper’s user id, fetchable via `GET /customers/{id}`.
`customers/subscribed`	`READ_CUSTOMERS`	A shopper subscribes to the newsletter.
`orders/placed`	`READ_ORDERS`	A shopper places an order (checkout from cart).
`orders/paid`	`READ_ORDERS`	A shopper’s order is confirmed paid.
`carts/item_added` · `carts/updated` · `carts/item_removed` · `carts/cleared` · `carts/abandoned`	`READ_CARTS`	Cart changes (add / update / remove / clear) and a cart the abandonment job has flagged. `resourceId` is the shopper’s user id, also sent as `customerId`.
`wishlists/item_added` · `wishlists/item_removed`	`READ_WISHLIST`	A shopper adds or removes a product from their wishlist. `resourceId` is the wishlist id, fetchable via `GET /wishlist/{id}`.
`reviews/created`	`READ_REVIEWS`	A shopper posts a product review. `resourceId` is the review id, fetchable via `GET /reviews/{id}`.

orders/placed and orders/paid are distinct from the admin orders/created/orders/updated. A single storefront checkout fires orders/placed (then later orders/paid) — never the admin topics. Use the resourceId (the order id) with READ_ORDERS to fetch the order via the Apps API.

Cart events fire only for signed-in shoppers. A guest (ghost) cart is not delivered: the storefront re-owns that cart to the real user when they sign in, so sending both would count the same cart twice. The abandonment job applies the same rule.

READ_CARTS on its own is notify-only: the envelope carries the customer id as resourceId and the shopId, but no cart contents. Add READ_CART_CONTENTS to fetch the cart with GET /carts/:customerId and to receive the cart aggregate on cart events. The fetch returns the line items; the event never does. See Carts. Wishlist events carry the wishlist id, fetchable with GET /wishlist/:id. See Wishlists.

Events fire for successful changes regardless of who made them — a merchant editing an order in the dashboard, another app, or a shopper on the storefront. Dedupe on id and treat delivery as at-least-once.

Billing events (charges and subscriptions)

Fired by Salesive when a payment your app asked for changes state. Unlike the topics above they are sent only to the app that made the charge, and need READ_CHARGES (to ask for charges at all you also need WRITE_CHARGES, so an app that wants these events requests both).

Topic	When it fires
`charges/paid` · `charges/declined` · `charges/expired`	A one-time charge or a subscription payment was paid, declined by the merchant, or timed out.
`charges/refunded`	A refund on the charge completed. Also carries a `refundId`.
`subscriptions/activated` · `subscriptions/renewed`	The first payment went through, or a renewal was taken.
`subscriptions/past_due`	A renewal failed and will be retried.
`subscriptions/trial_ending`	A subscription’s free trial ends in 3 days.
`subscriptions/approaching_cap`	The period’s usage reached 90% of the subscription’s usage cap. Fires once per period.
`subscriptions/cancel_scheduled` · `subscriptions/cancelled`	It will end at the end of the paid period, or it ended.
`subscriptions/declined` · `subscriptions/expired`	The merchant declined it, or never approved it.

resourceId is the charge or subscription id. Subscription events caused by a payment also carry a chargeId. See Payments.

Fetch the current data

The payload carries no record fields — when you receive an event, read the current state from the Apps API using your app access token and the resource + resourceId:

# e.g. an orders/updated event with resourceId 66b1f0a3c2d4e5f6a7b8c9d0
curl https://api.salesive.com/api/v1/orders/66b1f0a3c2d4e5f6a7b8c9d0 \
  -H "Authorization: Bearer app_<your-app-access-token>"

Re-fetching is deliberate, and safer than a fat payload:

You only ever see data you’re entitled to. The record comes back through your scoped token, so the webhook can never hand you fields your permissions don’t cover.
You always act on the latest state, not a snapshot that may be stale by the time you process it.

On a deleted event the record is gone — don’t re-fetch; act on resource + resourceId. When resourceId is absent (bulk or sub-actions), re-list the affected resource to re-sync the collection.

Verify the signature

Every delivery carries two signatures. Verify the newer one; the older one stays for receivers that have not moved yet. X-Salesive-Signature (current). The header is t=<unix seconds>,v1=<signature>, where the signature is the base64 HMAC-SHA256 of the string <t>.<raw body>, keyed with your app’s signing secret. The timestamp is part of the signed string, so an attacker cannot re-date a captured request.

Reject a delivery whose t is more than 300 seconds away from your own clock, in either direction. That tolerance is what makes a replay detectable.

Verify against the raw request body bytes, exactly as received, before any JSON parsing or re-serialization. Re-stringifying the parsed object changes the bytes and breaks verification.

Node.js (Express)

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);
};

// Capture the RAW body for signature verification.
app.post(
  "/webhooks/salesive",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const header = req.get("X-Salesive-Signature") || "";
    const parts = Object.fromEntries(
      header.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) // req.body is a Buffer of the raw bytes
      .digest("base64");

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

    const event = JSON.parse(req.body.toString("utf8"));
    // TODO: enqueue and process async; respond fast.
    console.log(event.topic, event.shopId, event.id);

    res.sendStatus(200);
  },
);

X-Salesive-Hmac-SHA256 (older). The base64 HMAC-SHA256 of the raw body, with no timestamp. It is still sent on every delivery so existing receivers keep working. It cannot detect a replay, so move to X-Salesive-Signature when you can.

Respond & retries

Acknowledge fast. Return a 2xx within 10 seconds. Do heavy work asynchronously. Anything else, including a timeout, is a failed attempt.
Retries. A failed attempt gets four retries, five attempts in total, with exponential backoff starting at 60 seconds and capped at one hour. Retries reuse the same event id, so make your handler idempotent (dedupe on id).
No retry for a bad URL. A URL that fails the guard is a permanent failure: it is logged once and not retried. A DNS failure stays retryable, because it may clear on its own.
At-least-once. You may occasionally receive a duplicate; never assume exactly-once.

Delivery log, replay and test events

Every attempt is logged for 14 days: the first try, each retry, each replay and each test. One row per attempt holds the topic, time, attempt number, duration, the HTTP status your endpoint answered (or a short error such as a timeout), the environment and the URL without its query string. Nothing secret is stored: no request or response body, no headers, no signature and no secret. Open your app in Apps > Developer and scroll to Webhook deliveries, or use the developer endpoints below. They require your merchant session, never an app_ token.

List deliveries

curl "https://api.salesive.com/api/v1/apps/developer/<appId>/webhook-deliveries?status=failed&limit=50" \
  -H "Authorization: Bearer <your-merchant-session-token>"

Filters: topic (for example orders/fulfilled), status (failed or delivered), limit (1 to 100, default 50) and cursor (the next value from the previous page; the older before name is also accepted). The response carries items, retentionDays and next.

Replay one delivery

curl -X POST "https://api.salesive.com/api/v1/apps/developer/<appId>/webhook-deliveries/<deliveryId>/replay" \
  -H "Authorization: Bearer <your-merchant-session-token>"

The log holds no body, so a replay rebuilds the notify-only envelope from the stored topic, resource, resourceId and shop. It gets a new event id, so it is a new delivery rather than a byte-for-byte copy: a dedupe check keyed on the original id will not suppress it. The replay goes to the installation’s current URL and is signed with the current secret for that environment, with one attempt and no retries. A replay is dropped, not retried, when the installation is gone or inactive, the app has no webhook URL for its environment, or the app’s webhookTopics no longer includes the topic: the queue call still answers queued, but nothing is sent. You can replay up to 30 deliveries an hour. resend is an accepted older name for the same operation.

Send a test event

curl -X POST "https://api.salesive.com/api/v1/apps/developer/<appId>/webhook-test" \
  -H "Authorization: Bearer <your-merchant-session-token>" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "app/test" }'

The only test topic is app/test. The event carries test: true, the installation id as resourceId and no store record. The app needs a webhook URL and at least one active installation; pass installationId to choose one, otherwise the most recent active installation is used. One attempt, no retries, up to 10 test events an hour. See Webhook deliveries for the response shapes.

Best practices

Verify the signature on every request; reject unsigned, stale or mismatched deliveries.
Process asynchronously (queue the event, ack immediately).
Scope your handling to the shopId. A delivery only ever concerns one store.
Don’t depend on ordering; use occurredAt if you need to reason about sequence.
Handle the mandatory topics (app/uninstalled, app/test, customers/redact, shop/redact, customers/data_request) even if you subscribe to a short list. See Data protection.

​Overview

​Enable webhooks

​Choose the topics you receive

​Payload shape

​Per-topic additions

​Example: a cart event with the aggregate

​Headers

​Topics

​Admin events (dashboard / API changes)

​Order, stock and lifecycle events

​Data protection topics

​Storefront events (live shopper activity)

​Billing events (charges and subscriptions)

​Fetch the current data

​Verify the signature

​Respond & retries

​Delivery log, replay and test events

​List deliveries

​Replay one delivery

​Send a test event

​Best practices

Overview

Enable webhooks

Choose the topics you receive

Payload shape

Per-topic additions

Example: a cart event with the aggregate

Headers

Topics

Admin events (dashboard / API changes)

Order, stock and lifecycle events

Data protection topics

Storefront events (live shopper activity)

Billing events (charges and subscriptions)

Fetch the current data

Verify the signature

Respond & retries

Delivery log, replay and test events

List deliveries

Replay one delivery

Send a test event

Best practices