Integrator webhooks

Overview

PuntoSuite can POST signed JSON events to HTTPS endpoints you register in the dashboard → Integrations page (staging). Events are emitted when synced sales reach the cloud (sync/push path).

Supported event types today:

• sale.completed
• inventory.low_stock (product updates with stock <= min_stock)

Register an endpoint

1. Sign in to the web dashboard.
2. Open Integrations (/integrations).
3. Add your HTTPS URL and comma-separated events (default sale.completed).
4. Copy the signing secret immediately — it is only shown once.

Verify signatures

Each delivery includes:

Header	Value
Content-Type	application/json
X-BodegaSuite-Event	e.g. sale.completed
X-BodegaSuite-Delivery-Id	UUID for this attempt
X-BodegaSuite-Signature	sha256=<hmac-hex>

Compute HMAC-SHA256 over the raw request body with your endpoint secret and compare to the header (constant-time).

import { createHmac, timingSafeEqual } from 'node:crypto'

function verify(secret: string, rawBody: string, header: string | null): boolean {
  if (!header?.startsWith('sha256=')) return false
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  const provided = header.slice(7)
  return (
    provided.length === expected.length &&
    timingSafeEqual(Buffer.from(provided), Buffer.from(expected))
  )
}

Sample sale.completed payload

{
  "event": "sale.completed",
  "occurredAt": "2026-05-22T18:00:00.000Z",
  "businessId": "default",
  "data": {
    "saleId": "clxyz…",
    "total": 1500,
    "totalSecondary": 68250,
    "registerId": "…",
    "sellerId": "…"
  }
}

Test receiver

Use webhook.site or a local tunnel, register the URL in Integrations, then click Send test or complete a sale on a licensed desktop and run Sync now in Settings.

Read API (stub)

Create an API key on the same page. Call:

GET /api/v1/export/sales?limit=25&businessId=default
X-API-Key: bs_live_…

Returns recent sales rows from cloud sync (read-only, rate-limited). Full versioning and catalog export remain roadmap items.