Overview
TimeLeaf provides a REST API for reading and writing data programmatically, and outbound webhooks for reacting to events in real time. REST API access is available on the Professional plan and above. Outbound webhooks require the Business plan and above.
REST API
The API uses standard REST conventions with JSON request and response bodies. All endpoints require authentication via an API key passed in the Authorization header.
Authentication
Authorization: Bearer tlk_your_api_key_here
Generate API keys under Settings > API > Keys. Each key has configurable scopes that limit which endpoints it can access.
Base URL
All API requests use your tenant subdomain:
https://your-company.timeleaf.app/api/v1/
Rate limits
API requests are rate-limited to 100 requests per minute per key. The response headers include X-RateLimit-Remaining and X-RateLimit-Reset so your integration can throttle accordingly.
Outbound webhooks
Webhooks send HTTP POST requests to your specified URL whenever an event occurs in TimeLeaf. This lets you build integrations without polling the API.
Event types
TimeLeaf supports 13 event types:
| Event | Trigger |
|---|---|
leave.requested | An employee submits a leave request |
leave.approved | A leave request is approved |
leave.rejected | A leave request is rejected |
leave.cancelled | A leave request is cancelled |
timesheet.submitted | An employee submits a weekly timesheet |
timesheet.approved | A timesheet is approved |
timesheet.rejected | A timesheet is rejected |
employee.created | A new employee is added |
employee.updated | An employee profile is updated |
employee.deactivated | An employee is deactivated |
shift.created | A shift is assigned |
shift.updated | A shift is modified |
overtime.alert | An overtime threshold is reached |
Creating a webhook
- Go to Settings > Integrations > Webhooks.
- Click New Webhook.
- Enter the endpoint URL where events should be sent.
- Select the event types you want to subscribe to.
- Save. TimeLeaf generates a signing secret for this webhook.
HMAC-SHA256 signing
Every webhook request includes a signature in the X-TimeLeaf-Signature header. The signature is an HMAC-SHA256 hash of the request body using your webhook's signing secret.
To verify a webhook delivery:
- Read the raw request body.
- Compute the HMAC-SHA256 hash using your signing secret.
- Compare the computed hash with the value in the
X-TimeLeaf-Signatureheader. - Reject the request if the signatures do not match.
Retry logic
If your endpoint returns a non-2xx status code or times out (30-second threshold), TimeLeaf retries the delivery using exponential backoff:
- Attempt 1. immediate
- Attempt 2. after 1 minute
- Attempt 3. after 5 minutes
After 3 failed attempts, the delivery is marked as failed. You can view failed deliveries and manually retry them from the webhook detail page.
Webhook management
From Settings > Integrations > Webhooks, you can:
- Create new webhooks with specific event subscriptions
- Update the endpoint URL or subscribed events
- Delete webhooks that are no longer needed
- View deliveries. a log of every delivery attempt, including the request payload, response status, and timing
Webhook payloads include the event type, a timestamp, and the full resource object. The payload structure is documented in the API reference under each event type.