Исходящие вебхуки позволяют вам получать информацию о событиях в вашем пространстве в реальном времени. Это могут быть новые сообщения, реакции, чаты, участники и тд.
Вебхук представляет собой
JSON
объект, отправляемый в момент наступления события на указанный в настройках бота
URL
, содержащий небольшое количество информации, которой достаточно для написания автоматизаций. Если требуется получить больше информации об объектах, указанных в
JSON
- вы можете воспользоваться
API
и получить полную информацию.
Доступны следующие типы событий:
- Новые сообщения
- Редактирование и удаление сообщений
- Добавление и удаление реакций
- Нажатие кнопок
- Изменение состава участников чатов
- Изменение состава участников пространства
Все настройки исходящих вебхуков находятся в чат-ботах. Создавая нового бота, вы получаете возможность указать
Webhook URL
и выбрать те события, которые вы хотите получать.
Большинство типов событий потребуют добавления бота в чаты. Именно по этим чатам и по отправленным ботом сообщениям вы будете получать события. Есть глобальные события (например, Изменение состава участников пространства), которые не требуют добавления бота в чат.
Данный вебхук отправляется при появлении нового сообщения в чате, где участвует бот.
Вы можете получать как все новые сообщения в чате, так и только те, которые начинаются с указанных команд. Это будет полезно, если вы не хотите получать поток событий, а вам нужно только по требованию пользователя вызвать какой-то сценарий.
| type | string | Тип объекта (для сообщений всегда message) |
| id | integer | Идентификатор сообщения |
| event | string | Тип события: new (новое сообщение), update (редактирование сообщения) или delete (удаление сообщения) |
| entity_type | string | Тип сущности, к которой относится сообщение: discussion (беседа или канал), thread (тред) или user (пользователь, если это личное сообщение) |
| entity_id | integer | Идентификатор сущности, к которой относится сообщение |
| content | string | Текст сообщения |
| user_id | integer | Идентификатор отправителя сообщения |
| created_at | string | Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
| url | string | Прямая ссылка на сообщение |
| chat_id | integer | Идентификатор чата, в котором находится сообщение |
| parent_message_id | integer или null | Идентификатор сообщения, к которому написан ответ. Возвращается как null, если сообщение не является ответом. |
| thread | object или null | Объект с параметрами треда. Возвращается как null, если это сообщение не относится к треду. |
| message_id | integer | Идентификатор сообщения, к которому был создан тред |
| message_chat_id | integer | Идентификатор чата сообщения, к которому был создан тред |
| webhook_timestamp | string | Дата и время отправки вебхука (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
Данный вебхук отправляется при редактировании или удалении сообщения в чате, где участвует бот.
Данный вебхук отправляется при добавлении или удалении реакции на сообщение в чате, где участвует бот.
| type | string | Тип объекта (для реакций всегда reaction) |
| event | string | Тип события: new (добавление реакции) или delete (удаление реакции) |
| message_id | integer | Идентификатор сообщения, к которому относится реакция |
| code | string | Emoji символ реакции |
| user_id | integer | Идентификатор пользователя, который добавил или удалил реакцию |
| created_at | string | Дата и время создания сообщения (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
| webhook_timestamp | string | Дата и время отправки вебхука (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
Данный вебхук отправляется при нажатии
Data-кнопки
в сообщении от бота. После получения этого вебхука вы можете воспользоваться методом Редактирование сообщения и изменить/удалить кнопки у сообщения или отправить Новое сообщение как реакцию пользователю.
| type | string | Тип объекта (для кнопки всегда button) |
| message_id | integer | Идентификатор сообщения, к которому относится кнопка |
| data | string | Данные нажатой кнопки |
| user_id | integer | Идентификатор пользователя, который нажал кнопку |
| webhook_timestamp | string | Дата и время отправки вебхука (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
Данный вебхук отправляется при изменении состава участников чатов, где состоит бот, и в тредах этих чатов.
| type | string | Тип объекта (для участника чата всегда chat_member) |
| event | string | Тип события: add (добавление) или remove (исключение) |
| chat_id | integer | Идентификатор чата, в котором изменился состав участников |
| thread_id | integer или null | Идентификатор треда. Возвращается как null, если чат не относится к треду. |
| user_ids | array of integers | Массив идентификаторов пользователей, с которыми произошло событие |
| created_at | string | Дата и время события (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
| webhook_timestamp | string | Дата и время отправки вебхука (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
Данный вебхук отправляется при изменении состава участников пространства, включая изменение состояния участников (смотреть на значение поля event).
| type | string | Тип объекта (для участника пространства всегда company_member) |
| event | string | Тип события: invite (добавление в пространство), confirm (принятие приглашения), suspend (деактивация доступа), activate (активация доступа) или delete (удаление) |
| user_ids | array of integers | Массив идентификаторов пользователей, с которыми произошло событие |
| created_at | string | Дата и время события (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
| webhook_timestamp | string | Дата и время отправки вебхука (ISO-8601, UTC+0) в формате YYYY-MM-DDThh:mm:ss.sssZ |
Каждый исходящий вебхук защищён с помощью подписи, основанной на хешировании содержимого. Подпись
HMAC
с использованием алгоритма
SHA256
вычисляется из тела запроса и передаётся в заголовке
Pachca-Signature
.
В теле вебхука также содержится поле
webhook_timestamp
— метка времени в формате UNIX, указывающая момент отправки вебхука. Рекомендуется проверять, что это значение находится в пределах одной минуты от времени получения запроса, чтобы предотвратить атаки повторной отправки (replay attacks).
Для проверки подписи необходимо вычислить её самостоятельно, используя секрет вебхука
Signing secret
, который доступен в настройках бота во вкладке «Исходящий webhook». Рекомендуется использовать сырой (raw) контент тела запроса для вычисления хеша, так как при JSON-парсинге содержимое может быть изменено.
//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"
}
Кроме проверки подписи, также рекомендуется валидировать IP-адреса отправителя.
IP-адрес Пачки:
37.200.70.177