Подписки на события
Как получать от Syncra POST-запрос на свой адрес, когда в рабочем пространстве пишут сообщение, меняют задачу или страницу базы знаний: список событий, тело запроса, проверка подписи и повторы.
Подписка на события — это ваш адрес, на который Syncra сама отправляет POST-запрос, когда что-то произошло: боту написали, задачу перенесли в другой статус, страницу базы знаний сохранили. Вашему сервису не нужно раз за разом спрашивать Syncra, не случилось ли чего: событие приходит само. Каждый запрос подписан секретом, так что сервис может убедиться, что запрос пришёл от Syncra. Подписку создаёт владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Подписки на события». Подписка принадлежит боту, поэтому сначала нужен бот: Боты.
Как создать подписку
- Откройте настройки рабочего пространства, вкладку «Боты», страницу бота.
- В разделе «Подписки на события» вставьте адрес своего сервиса в поле «Адрес запроса», например
https://example.com/syncra/events. Длина адреса — до 2048 символов. - В блоке «События» отметьте нужные. Они разбиты на группы «Чат», «Задачи» и «Вики». Нужно выбрать хотя бы одно.
- Нажмите «Добавить подписку».
- В строке подписки найдите «Секрет подписи» и нажмите «Показать». Скопируйте значение, оно начинается с
whsec_. Этим секретом ваш сервис проверяет подпись. - Нажмите «Отправить тест». Syncra отправит на ваш адрес событие
test. Результат появится в списке «Последние отправки» ниже.
У каждой подписки свой секрет. У одного бота может быть несколько подписок на разные адреса. Подписку можно изменить кнопкой «Изменить», остановить переключателем в её строке и убрать кнопкой «Удалить». Вместе с подпиской удаляется её журнал отправок.
События
| Событие | Название в настройках | Когда приходит |
|---|---|---|
bot.mentioned |
«Бота упомянули» | Бота упомянули через @ в чате, где он состоит. |
dm.received |
«Личное сообщение» | Человек написал боту в личные сообщения. |
message.created |
«Новое сообщение» | Любое сообщение в канале или групповой переписке, где состоит бот. |
task.created |
«Задача создана» | В рабочем пространстве создали задачу. |
task.assigned |
«Задача назначена» | У задачи сменился исполнитель, в том числе на бота. |
task.status_changed |
«Статус задачи изменён» | Задачу перенесли в другой статус. |
task.completed |
«Задача выполнена» | Задачу выполнили или открыли снова. Что именно, видно по полю task.isCompleted. |
task.comment_added |
«Комментарий к задаче» | К задаче добавили комментарий. |
wiki.page_created |
«Страница вики создана» | В базе знаний создали страницу. |
wiki.page_updated |
«Страница вики изменена» | Содержимое страницы базы знаний сохранили. |
Правила, по которым Syncra решает, отправлять ли событие:
- События чата приходят только из чатов, где бот состоит. Добавить бота в канал можно в разделе «Каналы» на его странице.
- Сообщения и действия ботов событий не создают. Так два бота не зациклятся друг на друге.
- Одно сообщение может подойти под два события. Если бота упомянули в канале и вы подписаны на
bot.mentionedи наmessage.created, придут два запроса. - Если человек отредактировал сообщение и добавил в него упоминание бота, придёт только
bot.mentionedс полемmessage.edited, равнымtrue. - Событие о голосовом сообщении без набранного текста приходит, когда готова его расшифровка.
- События задач и базы знаний приходят со всего рабочего пространства. Исключение — закрытый проект: события о его задачах и страницах получает только бот, который этот проект создал.
Запрос, который отправляет Syncra
POST ваш адрес запроса
Syncra отправляет этот запрос на адрес из поля «Адрес запроса» при каждом событии из подписки.
Заголовки:
| Заголовок | Значение | Описание |
|---|---|---|
Content-Type |
application/json |
Тело запроса — JSON. |
X-Syncra-Event |
имя события | Например task.created. У тестовой отправки — test. |
X-Syncra-Timestamp |
число | Время отправки этой попытки в секундах Unix. |
X-Syncra-Signature |
v1=<hex> |
Подпись запроса. Как её проверить, описано ниже. |
Поля тела, общие для всех событий:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
event |
string | да | Имя события. |
workspaceId |
string | да | Номер рабочего пространства. |
bot |
object | да | Бот, которому принадлежит подписка: id, userId, name. |
timestamp |
string | да | Время, когда Syncra создала событие. Формат ISO 8601, UTC. |
Остальные поля зависят от группы события.
События чата
Приходят с bot.mentioned, dm.received и message.created.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
channel |
object | да | Чат: id, name, type. Тип — public, private, dm или groupDm. |
message.id |
string | да | Номер сообщения. |
message.body |
string | да | Текст в том виде, в каком он хранится. Упоминания в нём записаны служебной разметкой. |
message.text |
string | да | Тот же текст для чтения: упоминания заменены на @Имя. У голосового сообщения без набранного текста здесь расшифровка. |
message.authorId |
string | да | Номер автора. |
message.authorName |
string или null | да | Имя автора. |
message.parentMessageId |
string или null | да | Номер первого сообщения ветки, если это ответ в ветке. |
message.createdAt |
string | да | Время сообщения, ISO 8601. |
message.edited |
boolean | нет | true, если событие вызвано правкой сообщения. |
message.voice |
boolean | нет | true у голосового или видеосообщения. |
message.transcript |
string или null | нет | Расшифровка записи. Приходит вместе с voice. |
message.forwardedFrom |
object | нет | Что переслали: authorName, text. Если переслали несколько сообщений, они приходят списком в поле messages. |
{
"event": "message.created",
"workspaceId": "...",
"bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
"channel": { "id": "...", "name": "releases", "type": "public" },
"message": {
"id": "...",
"body": "Выкатываем 2.14 в пятницу",
"text": "Выкатываем 2.14 в пятницу",
"authorId": "...",
"authorName": "Анна Ким",
"parentMessageId": null,
"createdAt": "2026-11-10T09:14:07.512Z"
},
"timestamp": "2026-11-10T09:14:07.840Z"
}
События задач
Приходят с task.created, task.assigned, task.status_changed, task.completed и task.comment_added.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
actor |
object | да | Кто это сделал: id, name. |
task.id |
string | да | Номер задачи. |
task.ref |
string или null | да | Короткий номер задачи, например SYN-298. Его части приходят отдельно, в полях task.key и task.number. |
task.title |
string | да | Название. |
task.description |
string или null | да | Описание. |
task.projectId, task.projectName |
string | да | Проект задачи. |
task.sectionId, task.sectionName |
string или null | да | Статус задачи: колонка на доске проекта. |
task.assigneeId |
string или null | да | Номер исполнителя. |
task.priority |
string | да | none, low, medium, high или urgent. |
task.isCompleted |
boolean | да | Выполнена ли задача. |
task.attachments |
array | да | Файлы задачи: id, name, contentType, size, url. |
task.url |
string | да | Путь к задаче без адреса сайта. Добавьте перед ним https://ai-syncra.ru. |
changes |
object или null | да | Что изменилось. У task.assigned это from и to, номера прежнего и нового исполнителя. У task.status_changed это fromSectionId, toSectionId, fromSectionName, toSectionName. У остальных событий null. |
comment |
object или null | да | Только у task.comment_added: id, authorId, authorName, body, text. У остальных событий null. |
{
"event": "task.status_changed",
"workspaceId": "...",
"bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
"actor": { "id": "...", "name": "Анна Ким" },
"task": {
"id": "...",
"key": "SYN",
"number": 298,
"ref": "SYN-298",
"title": "Обновить страницу тарифов",
"description": null,
"projectId": "...",
"projectName": "Сайт",
"sectionId": "...",
"sectionName": "В работе",
"assigneeId": null,
"priority": "medium",
"isCompleted": false,
"attachments": [],
"url": "/w/acme/tasks?taskId=SYN-298"
},
"changes": {
"fromSectionId": "...",
"toSectionId": "...",
"fromSectionName": "Очередь",
"toSectionName": "В работе"
},
"comment": null,
"timestamp": "2026-11-10T09:20:31.105Z"
}
События базы знаний
Приходят с wiki.page_created и wiki.page_updated.
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
actor |
object | да | Кто это сделал: id, name. |
page.id |
string | да | Номер страницы. |
page.ref |
string или null | да | Короткий номер страницы, например SYN-412. Его части приходят отдельно, в полях page.key и page.number. |
page.spaceId |
string | да | Номер раздела базы знаний. |
page.slug |
string | да | Имя страницы в адресе. |
page.title |
string | да | Заголовок. |
page.text |
string | да | Весь текст страницы без оформления. У длинной страницы тело запроса большое. |
page.url |
string | да | Путь к странице без адреса сайта. |
{
"event": "wiki.page_updated",
"workspaceId": "...",
"bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
"actor": { "id": "...", "name": "Анна Ким" },
"page": {
"id": "...",
"key": "SYN",
"number": 412,
"ref": "SYN-412",
"spaceId": "...",
"slug": "release-checklist",
"title": "Чек-лист релиза",
"text": "Перед релизом проверьте...",
"url": "/w/acme/wiki/site/release-checklist"
},
"timestamp": "2026-11-10T09:31:44.220Z"
}
Тестовое событие
Его отправляет кнопка «Отправить тест». В заголовке X-Syncra-Event стоит test.
{
"event": "test",
"workspaceId": "...",
"bot": { "id": "...", "userId": "...", "name": "Deploy bot" },
"channel": null,
"message": null,
"timestamp": "2026-11-10T09:00:00.000Z"
}
Что ответить
Ответьте любым статусом 2xx за 5 секунд. Тело ответа Syncra не читает. Если обработка занимает больше времени, сначала ответьте 200, а обработку выполните потом.
Ответ 200 OK, которого достаточно:
{ "ok": true }
Проверить обработчик без Syncra
Команда ниже запускается в терминале. Она собирает такой же запрос, какой отправляет Syncra, и подписывает его вашим секретом. Подставьте адрес своего обработчика.
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"
Проверка подписи
Подпись — это HMAC SHA-256 в шестнадцатеричной записи. Ключ — секрет подписки. Подписывается строка из трёх частей подряд: значение заголовка X-Syncra-Timestamp, точка, тело запроса.
X-Syncra-Signature: v1=HMAC_SHA256(secret, "<timestamp>.<тело запроса>")
Три правила:
- Считайте подпись по телу в том виде, в каком оно пришло, до разбора JSON. После разбора и повторной сборки байты могут отличаться, и подпись не сойдётся.
- Сравнивайте подписи функцией, время работы которой не зависит от того, где строки расходятся:
timingSafeEqualв Node.js,hmac.compare_digestв Python. Обычное==позволяет подобрать подпись по времени ответа. - Syncra не задаёт срок годности запроса. Решите сами, насколько старый
X-Syncra-Timestampвы принимаете, например не старше пяти минут.
Обработчик на Node.js без сторонних библиотек:
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);
Та же проверка на 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())
Доставка и повторы
- Успех — любой ответ
2xx. Другой статус, сетевая ошибка или молчание дольше 5 секунд считаются неудачей. - После неудачи Syncra пробует снова. Всего попыток до пяти. Пауза перед повтором начинается с одной секунды и каждый раз удваивается.
- У каждой попытки свои
X-Syncra-Timestampи подпись. Тело запроса при повторах не меняется. - После пятой неудачи отправка получает статус
failed. Отправить её заново нельзя. - Если подписку или бота выключили, пока событие ждало отправки, оно не уйдёт. В журнале будет причина
subscription or bot disabled. - Порядок событий не гарантирован. Событие, созданное позже, может прийти раньше. Сортируйте по полю
timestampиз тела. - Событие может прийти дважды, если ваш сервис обработал запрос, но ответил позже 5 секунд. Отдельного номера доставки в запросе нет. Чтобы не обработать событие повторно, запоминайте сочетание
event, номера объекта (message.id,task.idилиpage.id) иtimestampиз тела.
Журнал отправок виден в списке «Последние отправки» на странице бота. В каждой строке есть событие, статус отправки (pending, ok или failed), число попыток, статус ответа вашего сервиса и текст последней ошибки.
Чего подписки не умеют
- Нет событий о реакциях, вступлении в канал и выходе из него, созвонах, встречах и сделках CRM.
- Нет повторной отправки вручную.
- Нет гарантии порядка.
- Адрес файла в
task.attachments[].urlоткрывается только участнику рабочего пространства, который вошёл в Syncra. Ключ бота его не открывает.
Чтобы ответить на событие сообщением, используйте API ботов. Чтобы изменить задачу, смотрите Задачи в API ботов. Общий список ограничений собран на странице Что есть и чего нет.