Guides

Start here

What Tillstack isQuickstartAuthentication

Getting data in

How data gets inSync API referenceYour payment providerReconciliation

Building on it

Terminal integrationSales, returns, shiftsCatalog and stockInventory ledgerCatalog layout on devicesProduct picturesReportsWebhooksEmail and EngageRunning without our UI

Using the console

Operator portalMerchant guide

Reference

Sandbox, OpenAPI, PostmanErrors and limitsSecurity

Building on it

Webhooks

Tillstack tells your system when something happens, instead of making you poll.

Events#

Event When data
sale.created A sale is recorded (not on an idempotent replay) saleId, receiptNo, branchId, terminalId, occurredAt, grossKobo, discountKobo, taxKobo, totalKobo, paidKobo, changeKobo
sale.returned A return is recorded returnId, saleId, refundKobo, refundTaxKobo, saleStatus, occurredAt
stock.low A sale takes a tracked variant from above its reorder level to at or below it (once per crossing) branchId, variantId, sku, onHand, reorderLevel
transaction.unmatched An approved purchase from the bank is still unmatched after the grace period (30 min; once per transaction) transactionId, terminalId, tid, rrn, amountKobo, occurredAt
import.completed A CSV import finishes importId, kind, status, totalRows, created, updated, unchanged, failed
webhook.test You press "send test" (never subscribable) message

Envelope: { "id": "<event id>", "type": "sale.created", "createdAt": "...", "livemode": true, "merchantId": "...", "data": { ... } }. Amounts are integer kobo. livemode:false means the event came from a sandbox tenant.

Who receives what#

An endpoint on an organization receives events from that organization and everything beneath it: an operator endpoint sees all its merchants; a merchant endpoint sees only that merchant; another operator never sees yours.

Managing endpoints#

POST /v1/organizations/{id}/webhooks {url, events?, description?} returns the signing secret whsec_… once. GET (list), PATCH …/{endpointId} (url / events / isActive), DELETE, POST …/{endpointId}/rotate-secret, POST …/{endpointId}/test, GET …/{endpointId}/deliveries?status=, POST …/{endpointId}/deliveries/{id}/retry. Allowed for an admin/owner, or an API key with webhooks:write. Up to 10 endpoints per organization. URLs must be public https (no credentials, no private addresses; checked again at connect time).

Verifying a delivery#

Headers: Tillstack-Event, Tillstack-Delivery, Tillstack-Timestamp (unix seconds), Tillstack-Signature: v1=<hex>. hex = HMAC-SHA256(secret, "{Tillstack-Timestamp}.{raw request body}"). Compare in constant time and reject timestamps more than 5 minutes old. Verify against the raw bytes, before parsing JSON.

js
const sig = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex')
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(header))

Delivery guarantees#

  • At-least-once. De-duplicate on the event id (a retry is byte-identical). Order is not guaranteed.
  • Answer any 2xx within 10 s. Otherwise it retries after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h (7 attempts), then is Dead; re-queue it with the retry call.
  • 50 failed deliveries in a row switch the endpoint off (isActive:false, with a reason); fix the receiver and PATCH isActive:true.
  • Events are written in the same database transaction as the change, so there is never an event for a rolled-back sale or a sale that lost its event.

How it runs#

OutboxMessage → WebhookDispatcher (hosted service, polls every 2 s): fan-out creates one WebhookDelivery per matching endpoint (unique per endpoint+event), then delivers with a lease so several API instances share the work. Config: Webhooks__Enabled, Webhooks__PollMilliseconds; Webhooks__AllowPrivateNetworks=true only in dev/tests (receiver on localhost). (Plan said RabbitMQ; the database queue is enough at this scale and keeps events transactional. RabbitMQ can replace the polling later.)