Исходящие вебхуки

Исходящие вебхуки позволяют вам получать информацию о событиях в вашем пространстве в реальном времени. Это могут быть новые сообщения, реакции, чаты, участники и тд.

Вебхук представляет собой JSON объект, отправляемый в момент наступления события на указанный в настройках бота URL, содержащий небольшое количество информации, которой достаточно для написания автоматизаций. Если требуется получить больше информации об объектах, указанных в JSON - вы можете воспользоваться API и получить полную информацию.

Каждый исходящий вебхук защищён с помощью подписи, основанной на хешировании содержимого. Подробнее об этом, а также о других методах проверки подлинности исходящего вебхука, вы можете прочитать в блоке Безопасность.

Как это работает

Типы событий

Сообщения

В настройках доступны два отдельных пункта:

• Новые сообщения — создание сообщений в чатах, где состоит бот, и в тредах этих чатов
• Редактирование и удаление сообщений — изменение текста, файлов или удаление сообщений в чатах, где состоит бот, и в тредах этих чатов

Настройка Игнорировать свои сообщения позволяет не получать вебхуки о сообщениях, отправленных самим ботом. Это предотвращает зацикливание, когда бот реагирует на собственные сообщения. Нажатия кнопок обрабатываются всегда, вне зависимости от этой настройки.

Для новых сообщений доступны два режима отслеживания:

• О любых сообщениях — все новые сообщения, включая треды
• Сообщения, начинающиеся с команд — только сообщения, начинающиеся с указанных команд (например, /help, /deploy). Команды начинаются с / и пишутся на английском. Полезно, если вы не хотите получать поток событий, а вам нужно вызвать сценарий только по требованию пользователя

Реакции

Вебхук отправляется при добавлении или удалении реакции на сообщение в чате, где состоит бот.

Нажатие кнопок

Вебхук отправляется при нажатии Data-кнопки в сообщении от бота. После получения вы можете PUTотредактировать сообщение — например, изменить или удалить кнопки — или POSTотправить новое как ответ пользователю. Подробнее — в разделе Кнопки в сообщениях.

Изменение участников чатов

Вебхук отправляется при изменении состава участников чатов, где состоит бот, и в тредах этих чатов.

Изменение участников пространства

Вебхук отправляется при добавлении, удалении или приостановке участников пространства. Не требует добавления бота в чат.

Отправка ссылок

Вебхук отправляется при появлении ссылки на один из доменов, указанных в настройках Unfurl-бота. Для получения таких событий необходимо создать специального Unfurl-бота. После получения вы можете воспользоваться методом POSTUnfurl (разворачивание ссылок) и создать предпросмотр ссылки в сообщении. Подробнее — в разделе Разворачивание ссылок.

Безопасность

Каждый исходящий вебхук защищён с помощью подписи, основанной на хешировании содержимого. Подпись HMAC с использованием алгоритма SHA256 вычисляется из тела запроса и передаётся в заголовке Pachca-Signature.

В теле вебхука также содержится поле webhook_timestamp — метка времени в формате UNIX, указывающая момент отправки вебхука. Рекомендуется проверять, что это значение находится в пределах одной минуты от времени получения запроса, чтобы предотвратить атаки повторной отправки (replay attacks).

POST https://yourweb.site/read HTTP/1.1host: yourweb.sitecontent-Type: application/jsonpachca-signature: a805d3470c263f4628cafc4ed66235d8fe2229891d1fcf4e400331adff5d8e5auser-agent: Faraday v2.12.2content-length: 358 {    "event": "new",    "type": "message",    "webhook_timestamp": 1744618734,    "chat_id": 918264,    "content": "Клиент просит поправить шапку, подробности в документе",    "user_id": 134412,    "id": 56431,    "created_at": "2025-04-14T08:18:54.000Z",    "parent_message_id": null,    "entity_type": "discussion",    "entity_id": 918264,    "thread": null,    "url": "https://app.pachca.com/chats/124511?message=56431"}

// WEBHOOK_SECRET - значение поля Signing secret во вкладке «Исходящий webhook» в настройках бота const signature = crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");if (signature !== request.headers['pachca-signature']) {    throw "Invalid signature"}

Поллинг

Если у вас нет возможности принимать входящие HTTP-запросы (локальная разработка, жёсткие firewall-правила), используйте поллинг — получение событий через API.

Бот автоматически сохраняет историю исходящих вебхуков, которую можно получить через API:

• GETСписок событий бота — получить накопленные события
• DELETEУдалить событие — удалить обработанное событие из очереди

Алгоритм: периодически запрашивайте список событий, обрабатывайте каждое и удаляйте обработанные.