Boom-in API Specification

TimeX ⇄ Boom-in Dispatch API · v1.0.0

Real-time dispatch verification integration between TimeX (timexapp.co.za) and Boom-in. Two endpoints: 1. TimeX pushes the published fleet schedule (drivers + vehicles + trailers + containers) to Boom-in. 2. Boom-in pushes each gate scan transaction back to TimeX for authoritative comparison & alerting. All requests are HMAC-SHA256 signed with a shared secret. Both sides implement the same signing scheme.

Swagger / OpenAPI link

Give Boom-in this URL — they can import it into Postman/Swagger to see the full contract.

https://timexapp.co.za/boomin-openapi.json

Authentication — HMAC-SHA256

Every request (both directions) is signed with the shared secret. The sender computes HMAC-SHA256(raw body, SHARED_SECRET) and sends it in the header:

X-Timex-Signature: sha256=<hex_digest>

The receiver recomputes the digest over the raw request body and compares (constant-time). Reject with

401

on mismatch. The same secret and scheme are used in both directions.

Endpoints

POST

/functions/boominScanWebhook

Boom-in → TimeX

Receive a gate scan transaction (Boom-in → TimeX)

Boom-in POSTs one composite payload per gate transaction (driver + vehicle + all trailers + all containers). TimeX matches it to the scheduled allocation and raises alerts on mismatch. Idempotent on scan_session_id.

Request body: ScanTransaction

200 Processed

400 Invalid payload

401 Invalid HMAC signature

POST

/timex/schedules

TimeX → Boom-in

Receive the published schedule batch (TimeX → Boom-in)

CONTRACT FOR BOOM-IN TO IMPLEMENT. TimeX POSTs a batch of allocations on publish / amend / cancel. One call per event (a full-day publish is a single batch). Boom-in must verify the X-Timex-Signature header, persist the latest version per allocation_number, and return the acknowledged allocation_numbers.

Request body: ScheduleBatch

200 Acknowledged

401 Invalid HMAC signature

Schemas

DriverRef

employee_number	string
first_name	string
last_name	string
licence_number	string — RSA driver's licence number — the match key Boom-in scans from the driver's licence card.

VehicleRef

fleet_number	string
registration	string — Vehicle registration / plate — the match key Boom-in scans from the vehicle disc.

TrailerRef

fleet_number	string
registration	string

ContainerRef

container_number	string
seal_number	string — Cargo seal number (optional per container)
linked_trailer_reg	string

ScheduleAllocation

allocation_number*	string
allocation_date*	string
shift	string
depot	string
exit_gate	string
route_job_reference	string
expected_destination	string
planned_departure	string
driver*	DriverRef
vehicle*	VehicleRef
trailers	array
containers	array
version	integer — Incremented on each amendment
status	string
published_at	string

ScheduleBatch

batch_id*	string
pushed_at*	string
action*	string
allocations*	array

ScannedDriver

licence_number	string — From scanned driver's licence
employee_number	string — Optional manual entry

ScannedVehicle

registration

string — From scanned vehicle disc

ScannedTrailer

registration

string

ScannedContainer

container_number	string
seal_number	string

ScanTransaction

scan_session_id*	string — Unique per gate transaction — used for idempotency
scan_timestamp*	string — UTC ISO-8601
gate*	string
scan_type*	string
checkpoint_label	string — Required when scan_type = checkpoint
scanned_driver	ScannedDriver
scanned_vehicle	ScannedVehicle
scanned_trailers	array
scanned_containers	array
scanner_user	string — Boom-in operator id (optional)
boomin_match_summary	object

ScanAck

ok	boolean
result	string
allocation_number	string
mismatch_items	array
scan_id	string

ScheduleAck

ok	boolean
acknowledged	array — allocation_numbers received

Error

error

string

Live webhook endpoint

https://timexapp.co.za/functions/boominScanWebhook

Test it from Fleet Management → Boom-in API tab.