Developers
API and webhooks
Connect Vailo to Zapier, Make, n8n or your own code: a REST API with API keys and signed webhooks for tasks, projects and time entries.
Connect Vailo to Zapier, Make, n8n or your own scripts. The API reads and changes tasks, projects and time entries of one workspace; webhooks tell your system the moment something changes. The API and webhooks are part of the Premium plan.
Quick start
- In Vailo open Settings > API (Owner and Admin can).
- Choose Create API key, give it a name, choose Read only or Read and write. Copy the key now: it is shown once.
- Call the API:
curl https://www.vailo.io/api/v1/me -H "Authorization: Bearer vlo_your_key"
{ "key": { "id": "…", "name": "Zapier", "scopes": ["read", "write"] }, "workspace": { "id": "…", "name": "Acme" } }
Authentication
Send the key in the Authorization header of every request: Authorization: Bearer vlo_…. Always use HTTPS.
- A key belongs to one workspace and acts as an integration, not as a person. It sees what an admin sees in the data below, nothing more.
- Scopes:
read(GET) andwrite(POST, PATCH, DELETE; includes read). - Only the hash of a key is stored. If you lose a key, create a new one. Revoking a key in Settings stops it immediately.
- A key stops working when the person who created it is removed from the workspace or loses the right to manage API keys.
- The API never exposes finance data: no hourly rates, pay, amounts, budgets, clients or billing. Fields that are not listed here do not exist in the API, and a request that sends one is rejected.
Conventions
- JSON in and out, field names in
snake_case, timestamps in ISO 8601 UTC, ids are UUIDs. - Errors have one shape, with a stable
codeand arequest_idto quote to support:
{ "error": { "code": "invalid_request", "message": "The request body is invalid", "details": { "title": "title is a required field" } }, "request_id": "…" }
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Invalid body, query parameter or unknown field |
| 401 | invalid_api_key | Missing, malformed or revoked key |
| 402 | plan_required | The workspace plan does not include the API |
| 403 | insufficient_scope | A read-only key tried to write |
| 404 | not_found | No such object in this workspace |
| 409 | conflict, entry_locked | Duplicate, archived project, or a time entry in a submitted or approved week |
| 413 | payload_too_large | Body over 64 KB |
| 422 | idempotency_key_reused | The same Idempotency-Key with a different request |
| 429 | rate_limited | Too many requests; wait for Retry-After seconds |
- Pagination: lists answer
{ "data": [...], "next_cursor": "…" | null }, newest first. Passlimit(1-100, default 25) andcursor(thenext_cursorof the previous page, unchanged). - Rate limit: 120 requests per minute per key. Every answer carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(unix seconds). - Idempotent writes: send an
Idempotency-Keyheader (any unique string, up to 200 characters) with a POST. Repeating the same request with the same key within 24 hours returns the original answer (headerIdempotent-Replayed: true) instead of creating a second object. Safe to retry after a timeout. - Fields you do not send keep their value on PATCH; send
nullto clear a nullable field.
Endpoints
| Method and path | Scope | What it does |
|---|---|---|
GET /me | read | The key and the workspace (a good "test connection") |
GET /projects, GET /projects/{id} | read | List (filter status) or read projects |
POST /projects | write | Create a project |
PATCH /projects/{id} | write | Change a project |
GET /tasks, GET /tasks/{id} | read | List (filters project_id, status, assignee_id, updated_since) or read tasks |
POST /tasks | write | Create a task |
PATCH /tasks/{id}, DELETE /tasks/{id} | write | Change or delete a task |
GET /time-entries, GET /time-entries/{id} | read | List (filters project_id, task_id, user_id, from, to) or read time entries |
POST /time-entries | write | Log time for a person |
PATCH /time-entries/{id}, DELETE /time-entries/{id} | write | Change or delete a time entry |
GET /members | read | People of the workspace (filter status, default active) |
All paths are under https://www.vailo.io/api/v1.
Projects
Fields: id, code, name, status (active, paused, inactive, archived), lead_id, deadline (YYYY-MM-DD), tags, visibility (workspace, restricted), created_at, updated_at.
Create with code (1-16 letters, digits or underscores, unique, cannot change later) and name; the rest is optional.
Tasks
Fields: id, code (for example WEB-12), project_id, title, description (plain text), status (to-do, in-progress, in-review, ready-for-testing, testing, done, archived; blocked can only be set in the app), priority (low, medium, high, urgent), assignee_id, reporter_id, tags, due_date, important, estimate_s (seconds), created_at, updated_at, completed_at.
curl -X POST https://www.vailo.io/api/v1/tasks \
-H "Authorization: Bearer vlo_your_key" -H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c0d0e-0001" \
-d '{ "project_id": "…", "title": "Review the contract", "priority": "high", "assignee_id": "…" }'
project_id is required when creating and cannot be changed afterwards. The assignee must be an active member (and a member of the project when it is restricted).
Time entries
Fields: id, project_id, task_id, user_id, day (YYYY-MM-DD), duration_s (1-86400), started_at, ended_at, description, tags, status (draft, submitted, approved, rejected), created_at, updated_at.
Create with user_id, project_id, day and duration_s; task_id must belong to the project. Entries of a submitted or approved timesheet week cannot be added, changed or deleted (409 entry_locked).
Members
Fields: id, name, email, role, job_title, status, joined_at. Use id as assignee_id, lead_id and user_id.
Webhooks
A webhook endpoint is a URL that Vailo calls with a signed POST when something changes. Add one in Settings > API (up to 10 per workspace; up to 20 active API keys). The URL must use https and be reachable from the internet; addresses inside private networks are refused.
Events
task.createdtask.updatedtask.completedtask.deletedtime_entry.createdtime_entry.updatedtime_entry.deletedproject.createdproject.updatedpingis sent by Send test event.
task.completed fires when a task moves to done and comes in addition to task.updated. Updates are only sent when a field listed in this documentation changed. Changes made through the API send events too, so an integration that both writes and listens should ignore events it caused (compare ids).
Payload
{
"id": "5fc5abf8-cf3d-4274-b9d2-b0ad49b77d38",
"type": "task.updated",
"created_at": "2026-11-21T10:15:00.000Z",
"workspace_id": "…",
"data": { "id": "…", "code": "WEB-12", "title": "Review the contract", "status": "done", "changed_fields": ["status"] }
}
data holds the fields of the object as documented above (without description; read the task for it). *.updated events add changed_fields. *.deleted events carry only the identifying fields (id, plus code, project_id, user_id, day where they apply). id is the event id: it stays the same across retries and for every endpoint, so use it to ignore duplicates.
Headers and signature
| Header | Value |
|---|---|
Vailo-Event-Id | The event id (same as id in the body) |
Vailo-Event-Type | For example task.created |
Vailo-Delivery-Id | Id of this delivery attempt record |
Vailo-Timestamp | Unix time in seconds when the request was signed |
Vailo-Signature | v1= and the hex HMAC-SHA256 of <timestamp>.<raw body> with your signing secret |
Verify every request: compute the HMAC over the raw body (before any JSON parsing), compare in constant time, and reject timestamps older than 5 minutes.
// Node.js (Express: use express.raw({ type: 'application/json' }) so req.body is the raw Buffer)
import { createHmac, timingSafeEqual } from 'node:crypto'
export function verifyVailo(secret, headers, rawBody) {
const timestamp = Number(headers['vailo-timestamp'])
if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false
const expected = 'v1=' + createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
const received = String(headers['vailo-signature'] ?? '')
return expected.length === received.length && timingSafeEqual(Buffer.from(expected), Buffer.from(received))
}
# Python
import hashlib, hmac, time
def verify_vailo(secret: str, headers: dict, raw_body: bytes) -> bool:
timestamp = int(headers.get("Vailo-Timestamp", "0"))
if abs(time.time() - timestamp) > 300:
return False
signed = str(timestamp).encode() + b"." + raw_body
expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, headers.get("Vailo-Signature", ""))
The signing secret (whsec_…) is shown once when you add the endpoint.
Delivery, retries and the delivery log
- Answer with any 2xx within 10 seconds. Redirects are not followed.
- Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours (six attempts in all), then marked failed.
- After 15 failed attempts in a row the endpoint is turned off (and at once on
410 Gone). Turn it on again in Settings after fixing the receiver; events during the pause are not replayed. - Deliveries normally arrive within about a minute of the change. Order is not guaranteed; use
updated_atto find the newest state. - Settings > API > Delivery log shows the last 100 deliveries per endpoint (status, HTTP code, error, payload) and lets you send one again.
Zapier, Make and n8n
- Zapier: use Webhooks by Zapier with "Catch Hook" as the trigger (paste its URL as the endpoint) and "Custom Request" as the action (
https://www.vailo.io/api/v1/tasks, headerAuthorization: Bearer vlo_…). - Make: a Custom webhook module as the trigger and an HTTP > Make a request module for the API.
- n8n: a Webhook node as the trigger and an HTTP Request node for the API.
Zapier, Make and n8n webhook URLs are secret links: they usually do not verify signatures, so keep the URL private.
What is not in the API
Clients, rates, budgets, reports, billing, chat, time off, comments, attachments, timesheet approval and member management are not available. Finance data (hourly rates, pay, amounts, budgets) is never part of the API or of webhooks.