Node Webhooks: Push Events to Your POS

A node can POST device events to a receiver you control. Use this for prompt updates without keeping an event-stream connection open. Delivery is best effort: events can be lost or delivered twice, so the receiver must handle both outcomes.

Configure a receiver

Run an HTTP receiver reachable from the node, then update its configuration. Replace the example addresses and secret. Add X-PN-Api-Key when the node's access mode requires it; see authentication.

curl --fail-with-body -X PUT http://192.168.86.34/config \
  -H 'Content-Type: application/json' \
  -d '{
    "webhook": {
      "url": "http://192.168.86.20:8099/pos/hook",
      "secret": "replace-with-a-random-shared-secret",
      "events": ["scan_read", "printer_status"]
    }
  }'

Use a secret generated for this receiver, and protect the configuration request: the local API uses HTTP. A restricted LAN receiver can operate without internet access; a remote receiver depends on the network path to that service. HTTPS webhook targets use certificate verification. Plain HTTP signs the body but does not encrypt it. Redirects are not followed, so configure the final URL directly.

The URL is used exactly as supplied. An unknown event name causes a 422 response. A changed URL clears the stored secret unless the same request supplies a new secret. An empty secret explicitly disables signing. Reading the configuration reports secretSet, never the secret itself.

Choose events

These names match the type values on GET /events. A new configuration defaults to scans and printer status. Omitting events from a later patch keeps the existing selection.

Request format

POST /pos/hook HTTP/1.1
Content-Type: application/json
X-PN-Node: pn-d938
X-PN-Seq: 42
X-PN-Signature: sha256=<64 hexadecimal characters>
 
{"node":"pn-d938","seq":42,"uptimeMs":1157,"event":{"type":"scan_read","endpoint":"scanner","value":"ORDER-1042","seq":17}}

There are two sequence numbers. The outer seq identifies a queued webhook across all subscribed event types. A scan's event.seq identifies its record in GET /scans. They are independent: outer webhook 42 can carry scan 17. Do not use X-PN-Seq as a scan-log cursor.

Verify the signature before using the event

X-PN-Signature contains HMAC-SHA256 over the exact request-body bytes. Capture those bytes before a JSON body parser changes them. This Node.js helper rejects a missing, empty, malformed or incorrect signature:

import { createHmac, timingSafeEqual } from "node:crypto";
 
export function verifyWebhook(rawBody, signature, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== "string" || !secret.length) {
    return false;
  }
  if (typeof signature !== "string" || signature.length !== 71 || !/^sha256=[0-9a-f]{64}$/i.test(signature)) {
    return false;
  }
  const supplied = Buffer.from(signature.slice(7), "hex");
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  return timingSafeEqual(supplied, expected);
}

Limit the incoming HTTP body size before calling the helper. Parse and validate the JSON only after verification. Check that the signed node matches the device expected for that secret, and use the signed body fields for processing. The node and sequence headers are convenient hints; they are not themselves covered by the body signature.

A node without a configured secret sends sha256=. A receiver requiring signed events must reject it. Never accept a request merely because its signature header is present.

Delivery limits

The two attempts carry the same body and signature. If your receiver processes the first attempt but its response is lost, the retry can deliver the event again. Deduplicate processing and return success for an already accepted event. Neither at-most-once nor at-least-once delivery is guaranteed. Queue contents do not survive a node reboot, and the node does not send a later backfill.

Recover missed scans while they remain available

GET /scans contains a 12-record RAM ring, including accepted and refused scans. Use a scan's event.seq to compare it with the seq in each scan-log row. A scan-sequence gap can include refused reads, so inspect the verdict before using a recovered value.

Poll promptly when reconnecting or when you detect a gap. Older reads are overwritten when the ring fills, and a restart clears it. The ring cannot guarantee recovery after an outage or replace your application's durable transaction record. Other webhook event types do not have a replay log in /scans; read the relevant current state and handle an unknown earlier outcome explicitly.

How barcode reads become scan-log records

Check delivery health

Read the webhook status in GET /status: delivered, dropped, queued, seq, lastStatus and lastAttemptAgoMs. A 2xx counts a delivery acknowledged by the receiver, not proof that its downstream business action completed. lastStatus: -1 means no HTTP status was received; it does not distinguish a failed connection from a lost response. Inspect receiver logs alongside these counters rather than diagnosing from queue length alone.

The simulator accepts webhook configuration but does not deliver outbound webhooks. Test your receiver locally with signed fixtures, then verify actual delivery and failure handling on the intended node and network.

Still stuck? Contact support with your node model, firmware version, and what happened. Include an error code if you have one.