TaskCamp
Documentation sections

TaskCamp for developers

REST API, bots and access keys, signed webhooks, the personal key, and connecting AI assistants over MCP. Keys, bots and webhooks are created in the app: profile menu → “Integrations”.

How it works

Data flows in two directions, and each has its own tool.

  • Outgoing — webhooks. You specify an address and the events; on every event we send a POST with a JSON body and a signature to that address.
  • Incoming — bots and their access keys. Your system calls TaskCamp REST methods with the bot key in a header: it reads and changes tasks, reads the comment feed with files and voice transcripts, writes comments and attaches files, makes approval decisions, manages lists, and sends direct messages to employees.

Both directions work within a single company: a webhook receives events of its own company only, and a bot key works only in its own company. The exception is the personal key: it belongs to a person and works in all of that person's companies.

Integration bots

A bot is a technical member of the company on whose behalf your system acts. Tasks, comments and messages created with its key are attributed to the bot: employees see its name and a “bot” label, and a tap opens the bot's card (what it does, who connected it). This way the integration does not depend on a particular person: an employee leaving the company will not stop it.

  • One bot — one system. Employees can tell who is writing to them (“1C: Accounting”, “CRM”), and the log and loop protection can tell who wrote what. A company can have up to 10 bots.
  • Permissions belong to the bot. The permissions selected in the bot apply to all of its keys and change immediately. Within its permissions a bot acts as a company administrator: it sees all lists and can change and complete any task.
  • A bot has one key. It is issued when the bot is created. To replace the key, click “Reissue key”: the new key is shown once, and the previous one keeps working for 1 more hour and then turns off by itself — paste the new key into your system within that time and the integration will not be interrupted. If the previous key has leaked, disable it right away (“Disable now”). Reissuing does not change the bot's name, chats or authorship.
  • Nobody can sign in as a bot, and it does not take up a seat in your plan. A bot cannot be a task assignee, a list member or a message recipient; it cannot be called.
  • A bot that is turned off — all its keys return 403 with reason: bot_disabled until the bot is turned on again. A deleted bot — its keys are revoked (401), and its records remain in history labelled “Bot deleted”.
  • Due dates without a time zone (dueDate, dueTime) are interpreted in the time zone the company owner had when the bot was created.

Keys issued before bots existed act on behalf of an employee, as before; new keys are issued to bots only.

Access keys and REST

Base URL: https://api-ehmbf75l5a-uc.a.run.app. The key is passed in every request:

Authorization: Bearer tc_live_…
Content-Type: application/json

The key is shown once, when it is issued. We store only its hash, so a key cannot be recovered — only reissued. A bot key acts on behalf of the bot; an old employee key acts on behalf of that employee.

Permissions

ScopeWhat it allows
tasks:readread tasks
tasks:writecreate, change, complete, reopen and delete tasks
comments:readread task comments, including voice transcripts
comments:writeadd comments to tasks, edit and delete your own
files:readget files of tasks and comments with download links
files:writeupload files to tasks and attach them to direct messages
lists:readread lists
lists:writecreate, rename, archive and delete lists
approvals:writeapprove, return, withdraw a decision and resubmit a document
employees:readread the company's employees and bots
messages:readread the direct conversation with an employee
messages:writesend direct messages to the company's employees (with files, files:write is needed too)
webhooks:managemanage webhooks via API (needed by Make; not required for manual setup)

Permissions added after a bot was created are not turned on automatically: select them in the bot's card.

Methods

MethodPurpose
GET /v1/mewho is acting with the key: id (of the bot or employee), companyId, isBot, isPersonal, name, scopes. The id is handy for telling your own comments from other people's
GET /v1/companiescompanies in which the key works: id, name, role. A bot key has exactly one; a personal key has all of the person's companies, see Personal key
GET /v1/tasksthe company's tasks, newest first; query filters: listId, assigneeId, completed=true|false. Returned in pages — see “Pagination” below
POST /v1/taskscreate a task: title, listId; optional assigneeId, dueDate (YYYY-MM-DD), dueTime (HH:MM), subscribers[], recurrence
GET /v1/tasks/:ida single task
PATCH /v1/tasks/:idchange fields: title, assigneeId, dueDate, dueTime, dueStartTime, subscribers, tags, completed; all others are ignored
POST /v1/tasks/:id/complete · /reopencomplete · reopen
DELETE /v1/tasks/:iddelete a task
GET /v1/tasks/:id/commentsthe task's comment feed, oldest first; permission comments:read — see Comments and files
POST /v1/tasks/:id/commentsadd a comment: content (or message) — the text; optional attachmentIds[] — files uploaded beforehand; permission comments:write
PATCH /v1/comments/:id · DELETEchange the text of your own comment (content) · delete your own comment together with its files; permission comments:write
GET /v1/tasks/:id/attachmentsfiles of the task and its comments with download links; permission files:read
POST /v1/tasks/:id/attachmentsupload a file to a task: fileName, contentBase64, optional mimeType — or the uploadId of a file uploaded via a link; permission files:write
POST /v1/uploadsa link to upload a large file (up to 2 GB) directly to storage: fileName, fileSize, optional mimeType; permission files:write — see Uploading via a link
POST /v1/tasks/:id/approval/approve · /return · /revoke · /resubmitan approval decision; permission approvals:write — see Approvals and lists
POST /v1/messagesa direct message to an employee: recipientId, text, optional attachments[] — files; permission messages:write — see Messages
GET /v1/messages?with=…the direct conversation with an employee, with files and voice transcripts; permission messages:read
GET /v1/lists · GET /v1/lists/:idthe company's lists · a single list: id, title, type, status (active · archived · deleted), tagIds, members, taskCount
POST /v1/lists · PATCH /v1/lists/:idcreate a list (title, optional tagIds[]) · rename it (title); permission lists:write
POST /v1/lists/:id/archive · /unarchive · DELETE /v1/lists/:idarchive · restore from the archive · move to the trash; permission lists:write
GET /v1/employeesthe company's active employees: id, email, firstName, lastName, phone, role (owner · admin · member · guest), isActive. Deactivated employees are returned only with ?includeInactive=true. Use it to fill in assigneeId and recipientId. Bots are not included here
GET /v1/botsthe company's bots: id (starts with bot_), name, description, isActive. Deleted bots are returned only with ?includeDeleted=true. Use it to name the author when createdById or authorId contains bot_…; permission employees:read
GET /v1/webhooks · POST · DELETE /v1/webhooks/:idwebhooks via API (the same as the “Company: outgoing” tab)

Pagination

GET /v1/tasks, GET /v1/tasks/:id/comments and GET /v1/tasks/:id/attachments return results in pages. The response body is an array, as before; the service information is in the headers.

  • ?limit= — page size from 1 to 500, 100 by default.
  • X-Next-Cursor — the continuation cursor. Pass it in the next request as the ?cursor= parameter with the same filters. No header means everything has been returned.
  • X-Total-Count — how many objects match the request in total.
  • X-Result-Truncated: true — more than 10,000 objects match the request, and the output is capped. Narrow the request with the listId, assigneeId, completed filters.
GET /v1/tasks?assigneeId=…&completed=false&limit=200
→ 200, X-Total-Count: 431, X-Next-Cursor: eyJ0Ijox…

GET /v1/tasks?assigneeId=…&completed=false&limit=200&cursor=eyJ0Ijox…

Idempotency

When creating a task, comment, list or message, or uploading a file, pass the header Idempotency-Key: <unique string> — 1 to 100 characters from A–Z a–z 0–9 _ -. Repeating the request with the same key returns the object already created instead of creating a duplicate. This matters for retries on your side: the network blinked, the response did not arrive, you sent the request again — and there is still one task. For tasks, comments and lists a key in a different format is silently ignored; for messages and files it is rejected with a 400 response.

Errors

The body of an error response: {"error": "reason as text", "reason": "machine_code"}; reason is not always present.

CodeMeaning
400an error in the request: a required field is missing, a value is invalid, an invalid Idempotency-Key for a message; a personal key without the company header (reason: company_required). Repeating the same request is pointless
401the key is missing, revoked or invalid; the key's bot has been deleted; the previous key has used up its hour after a reissue (reason: key_expired)
403the required permission is missing; the key's bot is turned off (reason: bot_disabled); the object belongs to another company; the owner of the personal key is not a member of the company from the header (reason: not_member); this employee cannot be messaged (see Messages)
404the object was not found
413a base64 file is larger than 20 MB (larger ones go via a POST /v1/uploads link), a file via a link is larger than 2 GB (reason: file_too_large)
409the Idempotency-Key has already been used for a different object; a file via a link is not uploaded yet (reason: upload_pending), was uploaded with a different size (upload_size_mismatch) or is already attached elsewhere (upload_already_used)
429the rate limit is exceeded; the Retry-After header says in how many seconds to retry
500 · 503a failure on our side — retry later with the same Idempotency-Key

Personal key

Any employee can issue a personal key for themselves in the “Personal key” tab. It belongs to the person, not to a company: it works in every company the person is a member of and acts on their behalf — tasks and comments created with the key appear under their own name, without the “bot” label. It is a key for your own AI assistant (Claude, ChatGPT and others) or your own script. For exchange between the company's systems you still need a bot: it does not depend on a particular person.

  • The company of the request goes in a header. There is one key for all companies, so pass X-TaskCamp-Company: <company id> in every request. Without the header only GET /v1/me and GET /v1/companies work; the rest return 400 with reason: company_required. A company you are not a member of returns 403 with reason: not_member.
  • The list of companies is returned by GET /v1/companies: id, name and your role in each.
  • Access is the same as yours in the app. The company owner sees all lists. An administrator and a member see the lists they are members or creators of. A guest sees only the lists they are a member of. Tasks and lists outside that scope return 404, as if they did not exist.
  • Permissions are selected when the key is issued and do not change; if you need different ones, issue a new key. The permissions are never wider than yours: a selected action works only where you can perform it yourself. Webhooks cannot be managed (webhooks:manage) with a personal key.
  • Up to 5 active keys per person — one key per assistant. A revoked key stops working immediately.
  • If you are removed from a company, the key stops working in it immediately; in the other companies it works as before.
curl https://api-ehmbf75l5a-uc.a.run.app/v1/companies \
  -H "Authorization: Bearer tc_live_…"
→ [{"id": "abc123", "name": "My company", "role": "owner"}, …]

curl "https://api-ehmbf75l5a-uc.a.run.app/v1/tasks?completed=false" \
  -H "Authorization: Bearer tc_live_…" \
  -H "X-TaskCamp-Company: abc123"

An AI assistant does not talk to TaskCamp directly but through an MCP server — an intermediary program that turns its requests into calls to this API. One personal key is enough for it: it learns the companies from GET /v1/companies and adds the header itself.

Connecting an AI assistant

TaskCamp connects to AI assistants — Claude, ChatGPT and others — using the MCP standard. The server address is the same for everyone: https://taskcamp.app/mcp. There is nothing to install. Any employee can connect: the assistant acts on their behalf and sees what they see, in all their companies.

  • Claude (website, desktop and mobile apps): settings → “Connectors” → add a custom connector → paste the server address. You can also open a pre-filled form right away: add TaskCamp to Claude.
  • ChatGPT: on chatgpt.com open the plugins section → “+” → “Add custom MCP server” → paste the address into the Server URL field; authentication is OAuth. A server can be added only on the website; after that you can use it in the apps as well.
  • Programs where the key is set in the settings (Claude Code, Cursor and the like): the same address, and in the header Authorization: Bearer tc_live_… — your personal key.

The names of menu items in Claude and ChatGPT change — look for the section about connectors, plugins or MCP servers.

What happens when you connect

  1. The assistant opens a TaskCamp page. If you are not signed in, you sign in first — the same way as in the app.
  2. The page shows which application is asking for access and where it will send you back, which account you are signed in with, and the list of permissions. Select the ones you need and click “Allow”. Creating lists, deciding on approvals and direct messages are not selected by default.
  3. You return to the assistant. Ask it: “Show my tasks in TaskCamp”.

What the assistant can do

  • Show your tasks across all companies, find a task by words in its title, and read it in full — with the conversation, voice transcripts and images; for other files it gives links.
  • Write, edit and delete its own comment; create, change, complete and delete a task; manage lists and decide on approvals — if you granted the permission.
  • Attach files to a comment or upload them to a task: the text and the files go as one comment, just like from the app.
  • Write to an employee in a direct chat on your behalf — text, files or both — and read the conversation with them to see the reply. This needs the “send direct messages” and “direct messages” permissions.
  • A file the assistant created itself is passed as content. A file from your computer goes via a one-time link: the TaskCamp server does not see your disk, so an assistant that can run commands (Claude Code and similar) first uploads the file via the link and then attaches it.

How to disconnect

Connections are shown in the “Personal key” tab next to the keys — marked “connection” and with the application's address. The “Disconnect” button closes access immediately; you can reconnect from the assistant itself. If you are removed from a company, the assistant stops seeing it at that same moment.

The consent page flags an unfamiliar application with a warning and shows the address it will send you back to. Allow access only if you have just started the connection yourself.

Comments and files

The content of a task is its title and the comment feed with files. To fetch a task in full you need three requests: GET /v1/tasks/:id, GET /v1/tasks/:id/comments and GET /v1/tasks/:id/attachments.

Comment

{
  "id": "…", "taskId": "…", "listId": "…",
  "authorId": "…", "authorName": "Maria Peters",    // for a bot — the bot's name; in a shared list — the partner company's name
  "message": "See the photo",                        // the text; a voice comment has the caption “🎵 Голосовое”, a files-only comment — “📎 Файлы” (literal values returned by the API)
  "transcript": null,                                // transcript of the voice comment
  "transcriptStatus": null,                          // pending · done · empty · failed · skipped
  "attachments": [ { "id": "att_…", "fileName": "a.jpg", "mimeType": "image/jpeg", "fileSize": 48213 } ],
  "createdAt": "2026-11-12T09:15:30.000Z", "updatedAt": null, "editedAt": null
}
  • Deleted comments are not returned.
  • Voice comment: message contains the caption “🎵 Голосовое” (the literal value marking a voice comment), the recording is in the attachment, and what was said is in transcript. Recognize a voice comment by a non-empty transcriptStatus. The transcript appears later than the comment itself: while transcriptStatus is pending, there is no text yet. The comment.transcribed event tells you when it is ready.
  • attachments contains only file descriptions. The download link comes from GET /v1/tasks/:id/attachments, by the same id.

File

{
  "id": "att_…", "taskId": "…",
  "commentId": "…",                    // the comment the file is attached to; null — a file of the task itself
  "fileName": "a.jpg", "mimeType": "image/jpeg", "fileSize": 48213,
  "width": 1280, "height": 960, "duration": null,
  "uploadedBy": "…", "uploadedAt": "2026-11-12T09:15:28.000Z",
  "url": "https://…",                  // the original
  "thumbUrl": "https://…",             // a reduced copy of the image, if there is one
  "urlExpiresAt": "2026-11-13T09:20:00.000Z"
}

The links are temporary and live for 24 hours — do not store them, request them again. Downloading by a link does not require the key.

Uploading a file

POST /v1/tasks/:id/attachments
{ "fileName": "result.png", "mimeType": "image/png", "contentBase64": "iVBORw0KGgo…" }
→ 201, the file in the same form as in GET

POST /v1/tasks/:id/comments
{ "content": "Done, screenshot attached", "attachmentIds": ["att_…"] }
  • The file is passed in the request body in base64, up to 20 MB.
  • An uploaded file is visible in the task right away. To place it inside a comment, pass its id in attachmentIds when creating the comment — up to 10 files per comment. A file can be attached to one comment only, and only in the same task.
  • A comment can consist of files alone, without text.
  • The same restrictions apply as in the app: the company's subscription, storage space, and the ban on changes in an archived list.

Uploading via a link

A large file (up to 2 GB), or a file that is inconvenient to encode in base64, is put directly into storage:

POST /v1/uploads
{ "fileName": "Catalog.xlsx", "fileSize": 48213, "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" }
→ 201 { "uploadId": "upl_…", "uploadUrl": "https://…", "method": "PUT", "headers": { "Content-Type": "…" }, "expiresAt": "…" }

curl -X PUT -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @Catalog.xlsx "https://…"

POST /v1/tasks/:id/attachments
{ "uploadId": "upl_…" }
→ 201, the file in the same form as in GET
  • fileSize is the exact size in bytes: it is part of the link's signature, and storage will not accept a file of a different size.
  • The link is valid for an hour; the uploaded file waits for a day. uploadId is accepted by POST /v1/tasks/:id/attachments and by attachments in POST /v1/messages; it can be used once. Repeating the same request with the same uploadId returns the same file.
  • An upload belongs to whoever acts with the key: someone else's uploadId returns 404.

Editing and deleting

PATCH /v1/comments/:id and DELETE /v1/comments/:id work only with your own comments — those written by this same bot (or by the employee of an old key). Someone else's comment returns 403, reason: not_author. Editing changes the text and keeps the comment's files; deleting removes the comment together with its files. If the company settings forbid editing or deleting your own comments, or the time allowed for it has expired, the response is 403 or 400.

Approvals and lists

Approvals

A document is submitted for approval when a task is created in an approval list (POST /v1/tasks with the listId of such a list): the route is taken from the list. The approval progress is visible in the task:

"approvalStatus": "in_review",          // in_review · approved · returned; null for a regular task
"approval": {
  "status": "in_review", "currentStageIndex": 0, "startedAt": "…",
  "actions": [ { "stageIndex": 0, "employeeId": "…", "status": "pending", "comment": null, "actionAt": null } ]
}
MethodAction
POST /v1/tasks/:id/approval/approveapprove at the current stage; optional comment
POST /v1/tasks/:id/approval/returnreturn for revision; comment is required
POST /v1/tasks/:id/approval/revokewithdraw your decision
POST /v1/tasks/:id/approval/resubmitresubmit after a return

The decision is made by whoever is acting with the key, and only if they are an approver at the current stage (resubmitting is done by the document's author). A bot cannot be an approver, so these methods make sense for old employee keys; a bot key gets 403. The response is the task after the action. A regular task returns 400, reason: not_approval.

Lists

Writing to lists follows the same rules as in the app:

  • Create — a bot creates a list as an administrator; it becomes the list's only member, and the others are added in the app. The title is up to 100 characters; if a list with the same title already exists, the response is 409.
  • Rename — allowed for a list member or the company owner. A bot can rename a list it created itself or was added to.
  • Archive, restore from the archive, delete — a bot can do this for any list of the company. Deletion is soft: the list goes to the trash and can be restored from the app.
  • The plan's limits on the number of lists apply in the same way as in the app.

Direct messages

POST /v1/messages sends a message on behalf of the key's bot to an employee of the same company. It is a regular messenger message: the employee gets a separate chat with the bot (with the “bot” label), and the message arrives unread, with a push notification on the phone. The bot cannot be replied to: instead of the input field the employee sees “This bot doesn't accept replies”, and messages cannot be forwarded to the bot either. Put everything needed to act into the message — for example, a link to the task. A personal key and an old employee key write on behalf of that person into their direct chat with the recipient — such a message can be replied to.

POST /v1/messages
Authorization: Bearer tc_live_…
Content-Type: application/json
Idempotency-Key: r12345-AbCdEf          // optional, but without it a retry creates a duplicate

{ "recipientId": "…", "text": "New review: 2★ …" }

{ "recipientId": "…", "text": "Catalog questions are attached",
  "attachments": [ { "fileName": "questions.html", "mimeType": "text/html", "contentBase64": "PCFkb2N0…" },
                   { "uploadId": "upl_…" } ] }
  • recipientId — the employee's id from GET /v1/employees.
  • attachments — up to 10 files: each is either fileName + contentBase64 (optional mimeType) or the uploadId of a file uploaded via a link (see Uploading via a link). Base64 is limited to 20 MB for all files of a request. The text and the files arrive as one message; the recipient sees the files just like ones sent from the app: name, type, size, download. The files:write permission is needed too. The response includes attachments: id, fileName, mimeType, fileSize.
  • text — up to 10,000 characters; non-empty when there are no files. Line breaks are preserved, and links become clickable. If the text contains an HTML tag (< immediately followed by a Latin letter or /, then >), the message is shown as HTML after sanitizing: the tags themselves are not visible, the allowed ones (bold, italic, link, list) format the text, the rest are removed while their content stays. When forwarding someone else's text (a review, an email), put a space after < before a Latin letter or / — then the text is shown as is.
  • The response is 201: {"chatId": "…", "messageId": "…"}.
  • A retry with the same Idempotency-Key returns the same 201 response with the header Idempotent-Replayed: true; there will be no second message and no second push notification. The same key with a different recipientId returns 409, reason: idempotency_key_reused.
  • The limit is 30 messages per minute per sender (bot); above it you get 429 with the Retry-After header. Spread a broadcast to many employees over time.
Code · reasonWhen
400recipientId is missing, there is neither text nor files, the text is longer than 10,000 characters, a file has no content, a message to yourself, an invalid Idempotency-Key
403 · bot_disabledthe key's bot is turned off
403 · sender_inactivean old employee key: the employee is deactivated in the company
404 · recipient_not_foundthe recipient is not among the registered employees of the key's company
403 · recipient_inactivethe recipient is deactivated in the company
403 · chat_no_bridgethe sender cannot see this employee: the sender has a restricted visibility scope, or one of the two is a guest with no shared list
409 · idempotency_key_reusedthe key has already been used for a message to a different recipient
429more than 30 messages per minute

Reading the conversation

GET /v1/messages?with=<employee id>&limit=30
→ 200 [ { "id": "…", "authorId": "…", "authorName": "Anna Petrova", "text": "Will check tomorrow",
          "transcript": null, "transcriptStatus": null,
          "attachments": [ { "id": "att_…", "fileName": "scan.pdf", "mimeType": "application/pdf", "fileSize": 122880,
                             "url": "https://…", "urlExpiresAt": "…" } ],
          "createdAt": "…", "editedAt": null }, … ]
  • The last limit messages (up to 200, 30 by default), oldest first. Deleted messages are not returned. No chat yet — an empty array.
  • Earlier ones — with before=<message id>; the header X-Has-More: true means there are earlier messages.
  • File links live for 24 hours. For a voice message the text is in transcript, as with comments.
  • Permission messages:read; only the conversation of whoever acts with the key is visible.

Events

A webhook receives only the events selected in it. The list is complete — the system does not send any other events yet.

EventWhen it is sent
task.createda task was created
task.updatedthe title, due date, priority or list was changed; changedFields says what exactly
task.completed · task.reopenedthe task was completed · reopened
task.assignedthe assignee changed
task.deletedthe task was deleted
comment.createda comment was added; the body contains message, attachments[] (file descriptions) and transcriptStatus (pending for a voice comment)
comment.updatedthe text or the set of files of a comment was changed; the body contains the new message and attachments[]
comment.deletedthe comment was deleted
comment.transcribedthe transcript of a voice comment is ready; the text is in transcript
attachment.created · attachment.deleteda file was added to a task · a file was deleted; the body contains id, taskId, fileName, and for an added file also mimeType, fileSize, uploadedBy
list.created · list.updated · list.archived · list.deletedthe list life cycle (list.updated covers the title and tags)
approval.submitted · approved · returned · revoked · resubmittedthe steps of a task's approval
employee.joined · employee.removedan employee joined the company · was removed from it

Envelope

{
  "id":         "…",                  // the fields of the event's object sit directly in the body root:
  "title":      "…",                  // a task, comment, list… — the set depends on the event
  "listId":     "…",
  …
  "eventId":    "3f6c1d2e-…",         // UUID, unique; use it to discard duplicates
  "eventType":  "task.completed",
  "occurredAt": "2026-09-07T10:15:30.000Z",
  "actor": { "type": "user" | "api" | "system", "employeeId": "…",
             "apiKeyId": "…", "name": "Main key",           // apiKeyId and name (of the key) — only for api
             "botId": "bot_…", "botName": "1C: Accounting" },  // only if a bot wrote it
  "chainDepth": 0                     // depth of the automation chain, see “Two-way exchange”
}

The body does not contain the object's creation or modification time — the moment of the event is in occurredAt. The comment text in comment.created and comment.updated is the message field.

Events contain no file links — only the file description and its id: get the link with a GET /v1/tasks/:id/attachments request. A file appears with the attachment.created event at the moment of upload, not yet linked to a comment (commentId: null); the comment.created that follows tells you which comment it ended up in. When a task is deleted, no events about deleting its comments and files are sent — task.deleted is enough.

actor says who caused the event: a person in the interface (user), an integration using a key (api, with the key specified; a bot key also has botId and botName, and employeeId equals the bot's id) or the system (system). Some actions are written by the interface directly, bypassing the application server — for example, completing a task; such events arrive with actor: null. Check that the field is present.

Request signature

Every request is signed with the webhook's secret. The header:

X-TaskCamp-Signature: t=1725700000,v1=5f3a…e91c

Here t is the send time in Unix seconds, and v1 is the hex HMAC-SHA256 of the string t + "." + raw request body. Verification on your side:

  1. Take the raw request body — the bytes before JSON parsing. Reformatted JSON produces a different signature.
  2. Parse the header: t and v1.
  3. Compute HMAC_SHA256(secret, t + "." + body) and compare it with v1 using a constant-time function.
  4. Reject the request if |now − t| > 300 seconds — protection against replay.
// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(parts.t + '.' + rawBody).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Service headers of every request: X-TaskCamp-Event — the event type, X-TaskCamp-Event-Id — its identifier (matches eventId in the body), X-TaskCamp-Delivery-Id — the delivery identifier (each retry has its own), X-TaskCamp-Attempt — the attempt number, X-TaskCamp-Timestamp — the same t as in the signature.

Delivery and retries

  • Success is any 2xx response. Respond quickly and process asynchronously: the response timeout is 10 seconds.
  • 408, 429, any 5xx and network errors — we retry: up to 10 attempts, with the pause doubling from 30 seconds to 1 hour.
  • Other 4xx — we do not retry: the request arrived and the recipient rejected it.
  • 410 Gone — the webhook is turned off immediately: this is how your server says the address is no longer served.
  • Redirects are not followed and count as a delivery error.
  • Auto-disable: 20 failed deliveries in a row and at least 24 hours since the first of them — the webhook is turned off, and the reason appears in the panel. You can turn it back on with the “Turn on” button.
  • Order is not guaranteed: a retry of one event may arrive after the next one. Rely on occurredAt and the object's state in the event body, not on the sequence.
  • The same eventId may arrive twice (for example, after a manual redelivery from the log). Keep your processing idempotent.

The delivery log in the panel is kept for 30 days: time, event, attempts, HTTP code, error. You can also redeliver manually from there.

Two-way exchange without loops

If your system both receives events and writes to TaskCamp via API, it is important not to get into a loop: you wrote a task → an event arrived → you wrote again. Here is what we do about it and what is needed from you:

  • Your own echo is not sent. A webhook created with a bot key via API does not receive events about changes made by that bot — including after the key is reissued. A webhook of an old employee key recognizes its echo only by the key itself. Webhooks created in the panel are not tied to a key and receive everything — turn on their “Also send events made by this same integration via API” option deliberately, or stick to one system = one bot.
  • Look at actor. If actor.botId is your bot (or actor.apiKeyId is your key), you made the change yourself.
  • Pass the chain depth back. Every event has chainDepth: for a change made by a person it is 0. When writing to TaskCamp in response to an event, pass this number unchanged in the header X-TaskCamp-Chain-Depth: <chainDepth of the event> — we add one ourselves, and the event about your write arrives with a depth one greater. An event with a depth of 5 or more is not sent: this is how an A → B → A chain breaks on the fifth round.
  • Circuit breaker. More than 20 events per minute for a single object — the stream for it stops for 15 minutes so that a loop cannot spin up. In the log such events are marked as skipped.
  • Empty changes produce no events: writing the same values again does not generate an event.

Make

The TaskCamp app in Make is the same keys and webhooks, just without code: a Make scenario creates the webhook itself via API and receives events with a trigger module. To connect, create a bot with the webhooks:manage permission and paste its key into the Make connection — the scenario's actions will be attributed to that bot.

The app has modules for everything described above:

  • Triggers — one module per event from the Events section: tasks, comments and voice transcripts, files, lists, approvals, employees.
  • Tasks — create, update, complete, reopen, delete, search, get one.
  • Comments and files — read a task's comment feed with transcripts, add, update and delete your own comment, get files with links, upload a file.
  • Lists — get, create, rename, archive, unarchive, delete.
  • Approvals — approve, return, withdraw a decision, resubmit. They work with an employee key: a bot cannot be an approver.
  • Messages and employees — a direct message to an employee (text and up to 10 files), the list of employees.

The bot needs the permissions for the modules you use — the same ones as in the table in Access keys and REST. A search returns up to 500 records per run.

Nothing found. Try a different word.