Settings
Register, Verify and Monitor Webhooks
A webhook tells an external system that a selected entity changed. It deliberately carries no sale, customer or stock record; the receiver fetches details with its own scoped API token.
- Menu path
- Manage -> Integrations -> Webhooks
- Verified from
- Posnic demo and current POS source reviewed on 2026-09-08
Technical source evidence
Live demo Webhooks tab audited 2026-09-04, frontend/modules/settings_write.html int-sub-webhooks and int_hook_modal, frontend/static/script/js/modules/js/settings.js webhook controls, api/src/realtime/webhooks.js, api/src/realtime/change-events.js
Prepare the Receiver
- Use a stable HTTPS endpoint. Plain HTTP is accepted only for localhost development.
- Make the endpoint return a 2xx response within 10 seconds.
- Store received delivery IDs and make processing idempotent so retries do not duplicate work.
- Create a separate scoped API token if the receiver needs to fetch records after a signal.
Register a Webhook
- Open Manage -> Integrations -> Webhooks and click New Webhook.
- Enter the HTTPS endpoint URL.
- Select only the required entities: sales, items, receivings, customers, suppliers, categories, registers, expenses, shifts or easytables.
- Create the subscription and copy the signing secret immediately. It is shown once.
- Store the secret at the receiver and trigger one harmless test change.
- Check Recent deliveries for the entity, URL, status, attempt count and time.
Verify Every Request
| Part | Value | Receiver action |
|---|---|---|
| Body | event, entity, at and shop | Parse only after signature verification; fetch business data separately. |
| X-Posnic-Signature | sha256=HMAC-SHA256(raw body, secret) | Recompute against the exact raw request body and compare safely. |
| X-Posnic-Delivery | Unique delivery ID | Use as an idempotency key and retain for troubleshooting. |
| X-Posnic-Event | change | Treat it as a change signal, not a record snapshot. |
Delivery and Retry Behavior
- Posnic records delivery intent before sending and never delays or fails the shop transaction that triggered it.
- Non-2xx responses, connection errors and the 10-second timeout retry with increasing delays of about 1 minute, 5 minutes, 25 minutes, 2 hours and 10 hours.
- After five failed attempts the delivery becomes dead and remains visible for diagnosis.
- Multiple pending changes for the same subscription and entity are coalesced into one signal.
- Retries drain during normal shop traffic, at most once a minute per process; an idle shop may not retry until activity resumes.
Investigate Failures
- Open Recent deliveries and identify pending or dead rows.
- Check the HTTP status, endpoint availability, TLS certificate and receiver logs for the matching delivery ID.
- Confirm the receiver returns 2xx quickly before doing slow downstream work.
- Verify the stored signing secret and raw-body HMAC implementation.
- If an endpoint is retired, remove its subscription. Pending deliveries for a removed subscription become dead rather than silently disappearing.