osFoundry / Platform
Входящие вебхуки
URL на каждое приложение или рабочее пространство для приёма событий. Проверка подписи под капотом.
Что это
Входящие вебхуки дают osFoundry адрес для приёма данных из внешнего мира. Вы выпускаете токен, ограниченный конкретным приложением, экземпляром и каналом, и osFoundry возвращает выделенный URL по пути /api/v1/webhooks/inbound/{id}. Внешние системы (Stripe, GitHub, Zapier, CI-конвейер, ваш собственный бэкенд) отправляют JSON методом POST на этот URL, и событие попадает в выбранный вами realtime-канал, где на него могут реагировать ваш чат, агенты и приложения. Никакого поллинга и никакого отдельного сервера интеграции запускать не нужно: эндпоинт и есть интеграция.\n\nПроверка подписи встроена изначально, а не приделана сверху. Каждый токен несёт секрет подписи HMAC-SHA256, который показывается ровно один раз в момент выпуска. Отправитель вычисляет подпись по полезной нагрузке и передаёт её в заголовке X-OsFoundry-Signature; osFoundry проверяет её при каждом запросе и отклоняет всё, что не подписано или изменено в пути. Когда нужно сменить ключ у отправителя, ротация секрета открывает семидневное льготное окно, в течение которого прежний секрет остаётся действительным, поэтому ротация никогда не теряет событие, находящееся в пути. Отзыв токена срабатывает мгновенно: эндпоинт сразу начинает возвращать 401, и это самый быстрый путь при утечке секрета или выводе интеграции из эксплуатации.\n\nПоскольку всё это работает внутри десктопного рабочего пространства osFoundry с моделью BYOK, входящее событие может запускать те же агенты, приложения и знания, с которыми вы уже работаете, без платы за интеграцию по числу мест и без крюка ваших данных через стороннего посредника. Каждый токен фиксирует время последнего использования и число запросов за 24 часа, так что вы видите, какие отправители активны, а платформа хранит последние 100 входящих запросов для повтора, превращая отладку вебхуков из угадывания в повторный прогон реальной полезной нагрузки.
Ключевые возможности
- Выпускайте выделенный URL приёма для каждого приложения, экземпляра и канала: внешние системы отправляют JSON-события методом POST прямо на этот эндпоинт по пути /api/v1/webhooks/inbound/{id}
- Каждый запрос проверяется по подписи HMAC-SHA256 из заголовка X-OsFoundry-Signature, поэтому неподписанные или подделанные полезные нагрузки отклоняются ещё до попадания в ваш канал
- Ротируйте секрет подписи с семидневным льготным окном, в течение которого старый секрет ещё проходит проверку, чтобы сменить ключ у отправителей, не теряя события
- Отзывайте токен мгновенно: в момент отзыва эндпоинт возвращает 401, отсекая утёкший или выведенный из эксплуатации отправитель
- Смотрите время последнего использования и число запросов за 24 часа по каждому токену и повторяйте последние 100 входящих запросов из настроек триггера, когда нужно отладить доставку
Сценарии использования
- Разработчик подключает Stripe: выпускает токен, ограниченный биллинговым каналом, направляет вебхук Stripe на этот URL и позволяет osFoundry отклонять любой POST, чья подпись HMAC не совпадает, ещё до того как он дойдёт до агента
- Инженер эксплуатации при утечке секрета: отзывает затронутый токен ради мгновенного 401 и выпускает новый, не роняя остальные интеграции, питающие рабочее пространство
- Автор автоматизаций подключает CI-конвейер: отправляет события статуса сборки методом POST в канал, где агент сортирует сбои, и с помощью повтора последних 100 запросов отлаживает форму полезной нагрузки
Часто задаваемые вопросы
Как osFoundry проверяет, что входящий вебхук подлинный?
У каждого входящего токена есть секрет подписи HMAC-SHA256. Отправитель вычисляет подпись по телу запроса и посылает её в заголовке X-OsFoundry-Signature, а osFoundry пересчитывает и сверяет её при каждом запросе. Запросы с отсутствующей или недействительной подписью отклоняются, поэтому публиковать в ваш канал может только система, у которой есть секрет. Секрет показывается один раз при выпуске: сохраните его сразу, ведь позже он повторно не выводится.
Что происходит с событиями в пути, когда я ротирую или отзываю токен?
Ротация даёт семидневное льготное окно, в котором проходят проверку и новый, и прежний секрет, так что вы можете обновить каждый отправитель, не теряя события во время перехода. Отзыв по замыслу противоположен: эндпоинт немедленно возвращает 401 и отсекает отправитель тут же, а именно это и нужно, если секрет утёк или интеграцию выводят из эксплуатации.
У меня один URL вебхука на всё, или их можно разграничить?
Каждый токен ограничен конкретным приложением, экземпляром и каналом и выпускает собственный URL по пути /api/v1/webhooks/inbound/{id}. Это значит, что отправитель не может публиковать в канал, к которому ему не давали доступ, а вы можете отозвать или ротировать отдельную интеграцию, не трогая остальные. Каждый токен также сообщает время последнего использования и число запросов за 24 часа, так что вы понимаете, какие эндпоинты действительно принимают трафик.