osFoundry / Platform
인바운드 웹훅
앱이나 워크스페이스별로 이벤트를 수신하는 URL. 서명 검증이 기본 내장되어 있습니다.
개요
인바운드 웹훅은 osFoundry에 외부 세계를 향한 수신 주소를 제공합니다. 특정 앱, 인스턴스, 채널로 범위가 한정된 토큰을 발급하면 osFoundry가 /api/v1/webhooks/inbound/{id} 아래의 전용 URL을 돌려줍니다. Stripe, GitHub, Zapier, CI 파이프라인, 직접 만든 백엔드 같은 외부 시스템이 그 URL로 JSON을 POST하면, 이벤트는 여러분이 고른 실시간 채널에 도착하고, 그곳에서 채팅과 에이전트, 앱이 그것을 처리할 수 있습니다. 폴링도 없고 따로 운영할 통합 서버도 없습니다. 엔드포인트 자체가 통합입니다.\n\n서명 검증은 나중에 덧붙인 것이 아니라 처음부터 내장돼 있습니다. 각 토큰은 HMAC-SHA256 서명 시크릿을 지니며, 이 값은 발급 시점에 딱 한 번만 표시됩니다. 발신 측은 페이로드에 대한 서명을 계산해 X-OsFoundry-Signature 헤더에 담아 보내고, osFoundry는 모든 요청마다 이를 검증하여 서명이 없거나 전송 중 변조된 것은 모두 거부합니다. 어떤 발신 측의 키를 교체해야 할 때, 시크릿을 교체하면 7일간의 유예 창이 열려 그동안 이전 시크릿도 계속 유효합니다. 그래서 교체 과정에서 처리 중인 이벤트를 놓치는 일이 없습니다. 토큰 취소는 즉시 반영됩니다. 엔드포인트가 그 즉시 401을 반환하기 시작하며, 이는 유출된 시크릿이나 폐기된 통합에 대응하는 가장 빠른 경로입니다.\n\n이 모든 것이 osFoundry의 BYOK 데스크톱 워크스페이스 안에서 돌아가므로, 들어온 이벤트는 여러분이 이미 쓰고 있는 바로 그 에이전트, 앱, 지식을 그대로 트리거할 수 있습니다. 좌석당 통합 비용도 없고, 데이터가 제3자 중개자를 거쳐 우회하는 일도 없습니다. 각 토큰은 마지막 사용 시각과 최근 24시간 요청 수를 기록해 어떤 발신 측이 활성 상태인지 보여주며, 플랫폼은 재전송을 위해 최근 100건의 인바운드 요청을 보관합니다. 덕분에 웹훅 디버깅은 어림짐작이 아니라 실제 페이로드를 다시 실행하는 작업이 됩니다.
주요 기능
- 앱, 인스턴스, 채널마다 전용 수신 URL을 발급합니다. 외부 시스템은 /api/v1/webhooks/inbound/{id} 아래의 그 엔드포인트로 JSON 이벤트를 곧바로 POST합니다
- 모든 요청은 X-OsFoundry-Signature 헤더의 HMAC-SHA256 서명으로 검증되므로, 서명이 없거나 변조된 페이로드는 채널에 도달하기 전에 거부됩니다
- 서명 시크릿을 7일간의 유예 창과 함께 교체할 수 있으며, 그 기간에는 기존 시크릿도 계속 유효해 이벤트를 잃지 않고 발신 측 키를 바꿀 수 있습니다
- 토큰을 즉시 취소할 수 있습니다. 취소되는 순간 엔드포인트가 401을 반환해 유출되거나 폐기된 발신 측을 차단합니다
- 토큰별로 마지막 사용 시각과 24시간 요청 수를 확인하고, 전달을 디버깅해야 할 때 트리거 설정에서 최근 100건의 인바운드 요청을 재전송합니다
활용 사례
- Stripe를 연결하는 개발자: 결제 채널로 범위를 한정한 토큰을 발급하고 Stripe 웹훅을 그 URL로 향하게 한 뒤, HMAC 서명이 맞지 않는 POST는 에이전트에 닿기 전에 osFoundry가 거부하도록 둡니다
- 시크릿이 유출된 운영 엔지니어: 영향받은 토큰을 취소해 즉시 401을 내고 새 토큰을 발급하되, 워크스페이스에 데이터를 공급하는 다른 통합은 내리지 않습니다
- CI 파이프라인을 잇는 자동화 구축자: 빌드 상태 이벤트를 에이전트가 실패를 분류하는 채널로 POST하고, 최근 100건 요청의 재전송으로 페이로드 형태를 디버깅합니다
자주 묻는 질문
osFoundry는 인바운드 웹훅이 진짜인지 어떻게 검증하나요?
각 인바운드 토큰에는 HMAC-SHA256 서명 시크릿이 있습니다. 발신 측이 요청 본문에 대한 서명을 계산해 X-OsFoundry-Signature 헤더로 보내면, osFoundry가 모든 요청마다 다시 계산해 비교합니다. 서명이 없거나 유효하지 않은 요청은 거부되므로, 시크릿을 가진 시스템만 여러분의 채널에 게시할 수 있습니다. 시크릿은 발급 시점에 한 번만 표시되니 그때 저장해 두세요. 이후에는 다시 보여주지 않습니다.
토큰을 교체하거나 취소하면 처리 중인 이벤트는 어떻게 되나요?
교체 시 7일간의 유예 창이 주어져 새 시크릿과 이전 시크릿이 모두 검증을 통과하므로, 전환 중에도 이벤트를 잃지 않고 모든 발신 측을 갱신할 수 있습니다. 취소는 설계상 그 반대입니다. 엔드포인트가 즉시 401을 반환해 발신 측을 그 자리에서 차단하며, 이는 시크릿이 유출되거나 통합을 폐기할 때 바로 원하는 동작입니다.
모든 것에 하나의 웹훅 URL을 쓰나요, 아니면 범위를 나눌 수 있나요?
각 토큰은 특정 앱, 인스턴스, 채널로 범위가 한정되며 /api/v1/webhooks/inbound/{id} 아래에 고유한 URL을 발급합니다. 따라서 어떤 발신 측도 허가받지 않은 채널에는 게시할 수 없고, 다른 통합을 건드리지 않고 단일 통합만 취소하거나 교체할 수 있습니다. 또한 각 토큰은 마지막 사용 시각과 24시간 요청 수를 보고하므로, 실제로 트래픽을 받는 엔드포인트가 어느 것인지 구분할 수 있습니다.