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.
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 andPATCHisActive: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.)