Webhooks

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). The URL must be HTTPS and publicly reachable. When you save it, the console shows your app’s signing secret (whsec_…) — you’ll use it to verify deliveries.

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

The request

Every delivery is a POST with a JSON body:

{
  "id": "8f1c2e3a-...-9b0d",
  "topic": "orders/updated",
  "resource": "orders",
  "action": "updated",
  "resourceId": "66b1f0a3c2d4e5f6a7b8c9d0",
  "shopId": "6680aabbccddeeff00112200",
  "occurredAt": "2026-06-28T18:42:11.000Z"
}

There is no record data in the payload — only the identifiers you need to fetch it.

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.
`occurredAt`	ISO-8601 timestamp.

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-Hmac-SHA256`	Base64 HMAC-SHA256 signature of the raw body (see below).

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, …). You receive a topic only if your installation holds the scope below.

Admin events (dashboard / API changes)

Resource	Required scope	Example topics
`orders`	`READ_ORDERS`	`orders/created`, `orders/updated`
`products` / `foods` / `services`	`READ_INVENTORY`	`products/updated`, `foods/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`

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`	`READ_CARTS`	Cart changes (add / update / remove / clear).
`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.

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.

READ_CARTS and the wishlists/* topics are notify-only with no fetch API — the envelope carries the cart/wishlist resourceId and shopId, but there is no endpoint to read cart or wishlist contents. They’re intended as triggers (e.g. abandoned-cart timing), not data sources.

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.

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 is signed so you can trust it came from Salesive and wasn’t altered. Compute the base64 HMAC-SHA256 of the raw request body using your app’s signing secret, and compare it to the X-Salesive-Hmac-SHA256 header with a constant-time check.

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

Node.js (Express)

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

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

// Capture the RAW body for signature verification.
app.post(
  "/webhooks/salesive",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Salesive-Hmac-SHA256") || "";
    const expected = crypto
      .createHmac("sha256", SIGNING_SECRET)
      .update(req.body) // req.body is a Buffer (the raw bytes)
      .digest("base64");

    const ok =
      signature.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

    if (!ok) 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);
  },
);

Respond & retries

Acknowledge fast. Return a 2xx within a few seconds. Do heavy work asynchronously — Salesive treats anything other than 2xx (or a timeout) as a failed delivery.
Retries. A failed delivery is retried with exponential backoff for several attempts before it’s dropped. Because retries reuse the same id, make your handler idempotent (dedupe on id).
At-least-once. You may occasionally receive a duplicate; never assume exactly-once.

Best practices

Verify the signature on every request; reject unsigned 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.

Overview

Blogs

Categories

Comments

Customers

Discounts

Domains

Emails

Foods

KYC

Notes

Notifications

Orders

Payouts

Products

Roles

Scripts

Services

Shipday

Shipping

Tasks

Overview

Enable webhooks

The request

Headers

Topics

Admin events (dashboard / API changes)

Storefront events (live shopper activity)

Fetch the current data

Verify the signature

Respond & retries

Best practices

​Overview

​Enable webhooks

​The request

​Headers

​Topics

​Admin events (dashboard / API changes)

​Storefront events (live shopper activity)

​Fetch the current data

​Verify the signature

​Respond & retries

​Best practices

Overview

Enable webhooks

The request

Headers

Topics

Admin events (dashboard / API changes)

Storefront events (live shopper activity)

Fetch the current data

Verify the signature

Respond & retries

Best practices