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

  1. In Vailo open Settings > API (Owner and Admin can).
  2. Choose Create API key, give it a name, choose Read only or Read and write. Copy the key now: it is shown once.
  3. 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) and write (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 code and a request_id to quote to support:
{ "error": { "code": "invalid_request", "message": "The request body is invalid", "details": { "title": "title is a required field" } }, "request_id": "…" }
StatuscodeMeaning
400invalid_requestInvalid body, query parameter or unknown field
401invalid_api_keyMissing, malformed or revoked key
402plan_requiredThe workspace plan does not include the API
403insufficient_scopeA read-only key tried to write
404not_foundNo such object in this workspace
409conflict, entry_lockedDuplicate, archived project, or a time entry in a submitted or approved week
413payload_too_largeBody over 64 KB
422idempotency_key_reusedThe same Idempotency-Key with a different request
429rate_limitedToo many requests; wait for Retry-After seconds
  • Pagination: lists answer { "data": [...], "next_cursor": "…" | null }, newest first. Pass limit (1-100, default 25) and cursor (the next_cursor of the previous page, unchanged).
  • Rate limit: 120 requests per minute per key. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (unix seconds).
  • Idempotent writes: send an Idempotency-Key header (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 (header Idempotent-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 null to clear a nullable field.

Endpoints

Method and pathScopeWhat it does
GET /mereadThe key and the workspace (a good "test connection")
GET /projects, GET /projects/{id}readList (filter status) or read projects
POST /projectswriteCreate a project
PATCH /projects/{id}writeChange a project
GET /tasks, GET /tasks/{id}readList (filters project_id, status, assignee_id, updated_since) or read tasks
POST /taskswriteCreate a task
PATCH /tasks/{id}, DELETE /tasks/{id}writeChange or delete a task
GET /time-entries, GET /time-entries/{id}readList (filters project_id, task_id, user_id, from, to) or read time entries
POST /time-entrieswriteLog time for a person
PATCH /time-entries/{id}, DELETE /time-entries/{id}writeChange or delete a time entry
GET /membersreadPeople 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.created
  • task.updated
  • task.completed
  • task.deleted
  • time_entry.created
  • time_entry.updated
  • time_entry.deleted
  • project.created
  • project.updated
  • ping is 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

HeaderValue
Vailo-Event-IdThe event id (same as id in the body)
Vailo-Event-TypeFor example task.created
Vailo-Delivery-IdId of this delivery attempt record
Vailo-TimestampUnix time in seconds when the request was signed
Vailo-Signaturev1= 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_at to 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, header Authorization: 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.