РазделПодписки на события

Подписки на события

Как получать от Syncra POST-запрос на свой адрес, когда в рабочем пространстве пишут сообщение, меняют задачу или страницу базы знаний: список событий, тело запроса, проверка подписи и повторы.

Подписка на события — это ваш адрес, на который Syncra сама отправляет POST-запрос, когда что-то произошло: боту написали, задачу перенесли в другой статус, страницу базы знаний сохранили. Вашему сервису не нужно раз за разом спрашивать Syncra, не случилось ли чего: событие приходит само. Каждый запрос подписан секретом, так что сервис может убедиться, что запрос пришёл от Syncra. Подписку создаёт владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Подписки на события». Подписка принадлежит боту, поэтому сначала нужен бот: Боты.

Как создать подписку

  1. Откройте настройки рабочего пространства, вкладку «Боты», страницу бота.
  2. В разделе «Подписки на события» вставьте адрес своего сервиса в поле «Адрес запроса», например https://example.com/syncra/events. Длина адреса — до 2048 символов.
  3. В блоке «События» отметьте нужные. Они разбиты на группы «Чат», «Задачи» и «Вики». Нужно выбрать хотя бы одно.
  4. Нажмите «Добавить подписку».
  5. В строке подписки найдите «Секрет подписи» и нажмите «Показать». Скопируйте значение, оно начинается с whsec_. Этим секретом ваш сервис проверяет подпись.
  6. Нажмите «Отправить тест». 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 ботов. Общий список ограничений собран на странице Что есть и чего нет.