API reference
Products, stock and orders, with request and response fields.
Developers
Stop polling for stock and order changes
Simplebks calls your URL when an order or a stock level changes, signed so you can trust it.
Set up an endpoint
Creating endpoints needs the Professional and Enterprise plans.
-
Open the screen
Go to Settings, Integrations, then Developer API, and find the Webhooks card.
-
Add endpoint
Press + Add endpoint, enter your HTTPS URL and tick the events you want.
-
Copy the signing secret
It starts with whsec_ and is shown only once. Keep it on your server.
-
Send test
Press Send test. Your endpoint receives a test.ping event. Reply with any 2xx status.
Events
| Event | When it fires | Data |
|---|---|---|
order.created | An order arrives through the public API | The full order |
order.updated | Payment, fulfilment or cancellation changes, whether your site reported it or staff did it in Simplebks | The full order when reported through the API. A smaller object (orderNumber, status, paymentStatus, total) when staff act in Simplebks |
stock.updated | Any stock movement: till sales, purchases, adjustments, web orders | items: a list of sku, name, quantity, updatedAt. Batched about once a minute, up to 200 products per batch |
Headers and body
Every delivery is a POST with a JSON body.
{
"event": "order.updated",
"createdAt": "2026-10-26T09:30:00.000Z",
"data": { }
}X-Simplebks-Eventcarries the event name.X-Simplebks-Timestampcarries the send time in milliseconds.X-Simplebks-Signaturecarriessha256=followed by an HMAC-SHA256 (hex) of the timestamp, a dot, then the raw request body, keyed with your signing secret.
Verify every delivery
Hash the raw body exactly as received, not a re-serialised copy.
const crypto = require('crypto')
function isValid(req, rawBody, secret) {
const ts = req.headers['x-simplebks-timestamp']
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`)
.digest('hex')
const given = req.headers['x-simplebks-signature'] || ''
return given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
}Delivery rules
What your endpoint can rely on.
- Reply fast. Answer with a 2xx status within 10 seconds. Anything else, or a timeout, counts as a failure.
- Retries. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marked dead.
- Replay. In Integration activity, press Replay next to a delivery to send it again. Replay needs the Professional plan or above.
- Be ready for repeats. Treat the event as at-least-once and make your handler safe to run twice.
- Check the age. Reject a delivery whose timestamp is far from your own clock.
Security
What Simplebks stores and how you take it back.
- The signing secret is sealed at rest. Simplebks keeps it encrypted and shows it to you once.
- Use HTTPS. The screen accepts http:// and https:// addresses. Use HTTPS so payloads and signatures are not exposed.
- Remove an endpoint any time. Press Remove on the Webhooks card. Deliveries to it stop.
FAQ
Which events can I subscribe to?
order.created, order.updated and stock.updated. There are no invoice, payment or customer events yet.
How do I know a request really came from Simplebks?
Check X-Simplebks-Signature. It is an HMAC-SHA256 of the timestamp, a dot and the raw body, keyed with your endpoint secret.
What if my server is down?
Simplebks retries after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marks the delivery dead. You can replay it from Integration activity.
Does stock.updated fire for every sale?
It fires for any stock movement, batched about once a minute with up to 200 products per batch.
Start free and add your first webhook endpoint.