API & webhooks in the admin sidebar. This is where OnTime’s machine interfaces are managed.
API keys
Issuing one
Issue a key
Give it a name that says what it is for — “Payroll export job”, not “key 2”.
Choose a scope
ReadOnly or ReadWrite.Both scopes currently grant exactly the same access. The public API surface is read-only — there are no public write routes — so a ReadWrite key behaves identically to a ReadOnly one. The scope records your intent and is what a future write route would gate on.
Copy the key
The key is shown exactly once. OnTime stores only a hash. If you lose it, revoke it and issue a new one — there is no way to retrieve it.
ont_ followed by a hex string.Using one
Send it as a bearer token:
Full details, including the endpoints available, are in the Developers tab.
Revoking
Immediate. A revoked key is refused on the next request.
There is no rotate action. Rotating means issuing a new key, updating your consumer, then revoking the old one — in that order, so you never have a gap.
Rate limit
600 requests per minute, per key.
The limiter holds its counters in process memory. Restarting the backend resets every key’s counter, and if OnTime is ever run as more than one instance each would allow 600 per minute independently. Treat 600 as the intended limit rather than a guaranteed ceiling.
Webhooks
Registering one
Give the endpoint URL
An HTTPS URL you control.
Copy the signing secret
Shown exactly once, like an API key. You need it to verify that deliveries genuinely came from OnTime.
Status
Which events fire
Nine event types, not the full notification catalog: leave approved and rejected, regularization approved and rejected, overtime approved and rejected, payslip published, Form 16 available, and message received.Everything else — comp-off earned, swap decisions, document verified — raises an in-app notification but never reaches a webhook.
The delivery log
Every outbound attempt, with its status.
Retries and the dead-letter queue
A failed delivery is retried with escalating backoff — roughly a minute, then quadrupling, up to eight attempts over about 22 hours. An event that exhausts all eight moves to Failed: the dead-letter queue.
Replay re-queues a failed delivery. Fix your endpoint, then replay.
Alerting
When an event lands in the dead-letter queue, every api:manage holder gets an in-app notification.
The alert fires on exhaustion, not on the first failure. A webhook flips to Failing on its very first failed attempt, but the notification only arrives once an event has burned through all eight retries — roughly 22 hours later.So an endpoint can show a red Failing badge for most of a day before anyone is actively told. Check the badge; do not wait for the alarm. (A transient failure that recovers on retry correctly never alerts at all.)
