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
- Open the workspace settings, go to the Bots tab and open the bot’s page.
- 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. - Under Events, tick the ones you need. They come in three groups: Chat, Tasks and Wiki. Pick at least one.
- Press Add subscription.
- 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. - Press Send test. Syncra sends a
testevent 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.mentionedandmessage.created, you get two requests. - If a person edits a message and adds a mention of the bot, only
bot.mentionedis sent, withmessage.editedset totrue. - 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-Timestampyou 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
2xxresponse. 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-Timestampand 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
timestampfield 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.idorpage.id) andtimestampfrom 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[].urlopens 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.