SectionEvent subscriptions

Event subscriptions

How to have Syncra send a signed POST request to your address when someone writes a message or changes a task or a knowledge base page, with the event list, the request body, the signature check and retries.

An event subscription is an address of yours that Syncra sends a POST request to when something happens: someone wrote to the bot, a task moved to another status, a knowledge base page was saved. Your service does not have to keep asking Syncra for changes: it receives the event and decides what to do. Every request is signed with a secret, so your service can check that it came from Syncra. A workspace owner or admin creates a subscription: workspace settings, the Bots tab, the bot’s page, the Event subscriptions section. A subscription belongs to a bot, so you need a bot first: Bots.

Create a subscription

  1. Open the workspace settings, go to the Bots tab and open the bot’s page.
  2. In Event subscriptions, paste your service’s address into Request URL, for example https://example.com/syncra/events. The address can be up to 2048 characters long.
  3. Under Events, tick the ones you need. They come in three groups: Chat, Tasks and Wiki. Pick at least one.
  4. Press Add subscription.
  5. In the subscription’s row, find Signing secret and press Reveal. Copy the value, it starts with whsec_. Your service uses this secret to check the signature.
  6. Press Send test. Syncra sends a test event to your address. The result shows up in the Recent deliveries list below.

Each subscription has its own secret. One bot can have several subscriptions to different addresses. You can change a subscription with Edit, pause it with the switch in its row, and remove it with Delete. Deleting a subscription also deletes its delivery log.

Events

Event Name in settings When it is sent
bot.mentioned Bot mentioned The bot was @mentioned in a chat it is a member of.
dm.received DM received A person wrote to the bot in a direct message.
message.created Message created Any message in a channel or group chat the bot is a member of.
task.created Task created A task was created in the workspace.
task.assigned Task assigned A task’s assignee changed, including to a bot.
task.status_changed Task status changed A task moved to a different status.
task.completed Task completed A task was completed or reopened. The task.isCompleted field tells you which.
task.comment_added Task comment added A comment was posted on a task.
wiki.page_created Wiki page created A knowledge base page was created.
wiki.page_updated Wiki page updated The content of a knowledge base page was saved.

The rules Syncra follows when it decides whether to send an event:

  • Chat events come only from chats the bot is a member of. You add a bot to a channel in the Channels section of its page.
  • Messages and actions by bots produce no events, so two bots cannot trigger each other in an endless loop.
  • One message can match two events. If the bot is mentioned in a channel and you subscribed to both bot.mentioned and message.created, you get two requests.
  • If a person edits a message and adds a mention of the bot, only bot.mentioned is sent, with message.edited set to true.
  • A voice message with no typed text is sent once its transcript is ready.
  • Task and knowledge base events cover the whole workspace. The exception is a private project: its tasks and pages go only to the bot that created that project.

The request Syncra sends

POST your Request URL

Syncra sends this request to the address from the Request URL field for every event in the subscription.

Headers:

Header Value Description
Content-Type application/json The body is JSON.
X-Syncra-Event event name For example task.created. A test delivery carries test.
X-Syncra-Timestamp number The time this attempt was sent, in Unix seconds.
X-Syncra-Signature v1=<hex> The request signature. The check is described below.

Body fields shared by all events:

Field Type Required Description
event string yes The event name.
workspaceId string yes The workspace id.
bot object yes The bot that owns the subscription: id, userId, name.
timestamp string yes The time Syncra created the event. ISO 8601, UTC.

The other fields depend on the event group.

Chat events

Sent with bot.mentioned, dm.received and message.created.

Field Type Required Description
channel object yes The chat: id, name, type. The type is public, private, dm or groupDm.
message.id string yes The message id.
message.body string yes The text as Syncra stores it. Mentions appear in Syncra’s internal format, not as readable names.
message.text string yes The same text for reading: mentions are replaced with @Name. For a voice message with no typed text this holds the transcript.
message.authorId string yes The author’s id.
message.authorName string or null yes The author’s name.
message.parentMessageId string or null yes The id of the thread’s first message, when this is a reply in a thread.
message.createdAt string yes The time of the message, ISO 8601.
message.edited boolean no true when the event was caused by an edit.
message.voice boolean no true for a voice or video message.
message.transcript string or null no The transcript of the recording. Comes together with voice.
message.forwardedFrom object no What was forwarded: authorName, text. When several messages were forwarded, they are in the messages list.
{
  "event": "message.created",
  "workspaceId": "...",
  "bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
  "channel": { "id": "...", "name": "releases", "type": "public" },
  "message": {
    "id": "...",
    "body": "We ship 2.14 on Friday",
    "text": "We ship 2.14 on Friday",
    "authorId": "...",
    "authorName": "Anna Kim",
    "parentMessageId": null,
    "createdAt": "2026-11-10T09:14:07.512Z"
  },
  "timestamp": "2026-11-10T09:14:07.840Z"
}

Task events

Sent with task.created, task.assigned, task.status_changed, task.completed and task.comment_added.

Field Type Required Description
actor object yes Who did it: id, name.
task.id string yes The task id.
task.ref string or null yes The task’s short reference, for example SYN-298. The task object also carries its two parts as separate fields, key and number.
task.title string yes The title.
task.description string or null yes The description.
task.projectId, task.projectName string yes The task’s project.
task.sectionId, task.sectionName string or null yes The task’s status: a column on the project board.
task.assigneeId string or null yes The assignee’s id.
task.priority string yes none, low, medium, high or urgent.
task.isCompleted boolean yes Whether the task is completed.
task.attachments array yes The task’s files: id, name, contentType, size, url.
task.url string yes The path to the task without the site address. Put https://ai-syncra.ru in front of it.
changes object or null yes What changed. For task.assigned it holds from and to, the ids of the previous and the new assignee. For task.status_changed it holds fromSectionId, toSectionId, fromSectionName, toSectionName. For other events it is null.
comment object or null yes Only for task.comment_added: id, authorId, authorName, body, text. For other events it is null.
{
  "event": "task.status_changed",
  "workspaceId": "...",
  "bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
  "actor": { "id": "...", "name": "Anna Kim" },
  "task": {
    "id": "...",
    "key": "SYN",
    "number": 298,
    "ref": "SYN-298",
    "title": "Update the pricing page",
    "description": null,
    "projectId": "...",
    "projectName": "Website",
    "sectionId": "...",
    "sectionName": "In progress",
    "assigneeId": null,
    "priority": "medium",
    "isCompleted": false,
    "attachments": [],
    "url": "/w/acme/tasks?taskId=SYN-298"
  },
  "changes": {
    "fromSectionId": "...",
    "toSectionId": "...",
    "fromSectionName": "Backlog",
    "toSectionName": "In progress"
  },
  "comment": null,
  "timestamp": "2026-11-10T09:20:31.105Z"
}

Knowledge base events

Sent with wiki.page_created and wiki.page_updated.

Field Type Required Description
actor object yes Who did it: id, name.
page.id string yes The page id.
page.ref string or null yes The page’s short reference, for example SYN-412. The page object also carries its two parts as separate fields, key and number.
page.spaceId string yes The id of the knowledge base space.
page.slug string yes The part of the page’s web address that names the page, for example release-checklist.
page.title string yes The title.
page.text string yes The whole text of the page without formatting. A long page makes a large request body.
page.url string yes The path to the page without the site address.
{
  "event": "wiki.page_updated",
  "workspaceId": "...",
  "bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
  "actor": { "id": "...", "name": "Anna Kim" },
  "page": {
    "id": "...",
    "key": "SYN",
    "number": 412,
    "ref": "SYN-412",
    "spaceId": "...",
    "slug": "release-checklist",
    "title": "Release checklist",
    "text": "Before a release, check...",
    "url": "/w/acme/wiki/site/release-checklist"
  },
  "timestamp": "2026-11-10T09:31:44.220Z"
}

The test event

The Send test button sends it. The X-Syncra-Event header carries test.

{
  "event": "test",
  "workspaceId": "...",
  "bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
  "channel": null,
  "message": null,
  "timestamp": "2026-11-10T09:00:00.000Z"
}

What to answer

Answer with any 2xx status within 5 seconds. Syncra does not read the response body. If your processing takes longer, answer 200 first and do the work afterwards.

A 200 OK response that is enough:

{ "ok": true }

Test your handler without Syncra

This command builds the same request Syncra sends and signs it with your secret. Put in the address of your own handler.

SECRET="whsec_..."
BODY='{"event":"test","workspaceId":"...","bot":{"id":"...","userId":"...","name":"Deploy bot"},"channel":null,"message":null,"timestamp":"2026-11-10T09:00:00.000Z"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -X POST "http://localhost:3000/syncra/events" \
  -H "Content-Type: application/json" \
  -H "X-Syncra-Event: test" \
  -H "X-Syncra-Timestamp: $TS" \
  -H "X-Syncra-Signature: v1=$SIG" \
  -d "$BODY"

Check the signature

The signature is an HMAC SHA-256 in hex. The key is the subscription’s secret. The signed string is three parts in a row: the value of the X-Syncra-Timestamp header, a dot, and the request body.

X-Syncra-Signature: v1=HMAC_SHA256(secret, "<timestamp>.<request body>")

Three rules:

  • Compute the signature over the body exactly as it arrived, before you parse the JSON. After parsing and re-serializing, the bytes can differ and the signature will not match.
  • Compare signatures with a constant-time function.
  • Syncra sets no expiry for a request. Decide for yourself how old an X-Syncra-Timestamp you accept, for example no older than five minutes.

A handler in Node.js with no third-party libraries:

import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = process.env.SYNCRA_SIGNING_SECRET; // whsec_...

function isFromSyncra(rawBody, timestamp, signature) {
  const expected = Buffer.from(
    "v1=" + createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex"),
  );
  const received = Buffer.from(String(signature ?? ""));
  return received.length === expected.length && timingSafeEqual(received, expected);
}

createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks);
    const timestamp = String(req.headers["x-syncra-timestamp"] ?? "");
    if (!isFromSyncra(rawBody, timestamp, req.headers["x-syncra-signature"])) {
      res.writeHead(401).end();
      return;
    }
    const payload = JSON.parse(rawBody.toString("utf8"));
    console.log(payload.event, payload.timestamp);
    res.writeHead(200).end();
  });
}).listen(3000);

The same check in Python:

import hashlib
import hmac


def is_from_syncra(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    expected = "v1=" + hmac.new(
        secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected.encode(), signature.encode())

Delivery and retries

  • Success is any 2xx response. Another status, a network error, or silence for longer than 5 seconds counts as a failure.
  • After a failure Syncra tries again, up to five attempts in total. The pause before a retry starts at one second and doubles each time.
  • Every attempt has its own X-Syncra-Timestamp and signature. The request body stays the same across retries.
  • After the fifth failure the delivery gets the status failed, and Syncra does not send that event again.
  • If the subscription or the bot is turned off while an event waits to be sent, the event does not go out. The log shows the reason subscription or bot disabled.
  • The order of events is not guaranteed. An event created later can arrive earlier. Sort by the timestamp field from the body.
  • An event can arrive twice if your service handled the request but answered later than 5 seconds. The request carries no separate delivery id. To avoid handling an event twice, remember the combination of event, the object’s id (message.id, task.id or page.id) and timestamp from the body.

The log is the Recent deliveries list on the bot’s page. Each row shows the event, the delivery status (pending, ok or failed), the number of attempts, your service’s response status and the text of the last error.

What subscriptions do not do

  • There are no events for reactions, joining or leaving a channel, calls, meetings or CRM deals.
  • There is no manual redelivery.
  • There is no guaranteed order.
  • The file address in task.attachments[].url opens only for a workspace member who is signed in to Syncra. A bot key does not open it.

To answer an event with a message, use the bot API. To change a task, see Tasks in the bot API. The full list of limits is on the What exists and what does not page.