범용 커넥터 구축: SaaS 롱테일

SchemaBridge Team · 2026-01-22 · SaaS, Integration, Webhooks

공식 SDK가 없는 레거시·니치 SaaS 연결하기. 범용 웹훅 패턴.

SaaS 롱테일: "빅 10" API 너머

Stripe, Salesforce, AWS용 통합을 만든다면 운이 좋은 편입니다. 이런 공급자에게는 최고 수준의 문서, 12개 언어로 된 공식 SDK, 그리고 Stack Overflow의 거대한 커뮤니티가 있습니다. 이들과의 연결은 이미 해결된 문제입니다. npm install stripe를 실행하고 코드 몇 줄을 복사하면 끝입니다.

하지만 현대 기업은 "빅 10" SaaS 플랫폼만으로 돌아가지 않습니다. 니치 SaaS 공급자의 롱테일, 업종 특화 버티컬 솔루션, 그리고 시간이 잊어버린 레거시 시스템 위에서 돌아갑니다. 베트남의 지역 급여 공급자, 독일의 의료기기 전문 클라우드, 혹은 2012년 이후로 API 문서가 갱신되지 않은 레거시 물류 ERP와 통신해야 할 수도 있습니다.

이런 공급자에게는 SDK가 거의 없습니다. 문서는 대개 비밀번호로 보호된 PDF이거나 이메일로 접근을 요청해야 하는 비공개 위키입니다. 인증 방식도 비표준입니다(예: 커스텀 헤더, 주기적으로 바뀌는 IP 화이트리스트, SOAP 기반 세션 토큰).

많은 통합 프로젝트가 멈춰 서는 곳이 바로 여기입니다. 맞춤형 보일러플레이트, 깨지기 쉬운 XML 파서, 커스텀 인증 핸들러의 늪에서 사라집니다. 팀은 이런 서비스를 위한 "래퍼"를 만드는 데 몇 달을 쏟고, 결국 그것을 운영하고 유지하는 일이 악몽이라는 사실을 깨닫게 됩니다.

범용 커넥터 패턴: 설계부터 스키마리스

SchemaBridge는 다른 길을 제안합니다. 맞춤형 래퍼 대신 구성입니다. 이를 가능하게 하는 기본 요소가 GATEWAY vertex, 즉 워크플로 그래프 안의 구성 가능한 HTTP 클라이언트 단계입니다. 재사용 가능한 설정(기본 URL, 헤더, 인증)은 워크스페이스의 custom app으로 한 번만 등록해 두면, 그것을 사용하는 모든 gateway에 미리 채워집니다.

이 모델에서 범용 커넥터란 새 코드를 작성하지 않고 니치 서비스에 맞게 "파라미터화"된 gateway일 뿐입니다. 통합 문제를 "코딩 문제"에서 "구성 문제"로 바꿉니다.

범용 커넥터의 구조

SchemaBridge에서 호출은 gateway vertex의 구성으로 기술됩니다. 구성은 코드가 아니라 상호작용의 "형태"를 정의합니다.

{
  "id": "fetch_order",
  "type": "GATEWAY",
  "config": {
    "url": "= 'https://api.localpayroll.vn/v1/orders/' & payload.id",
    "method": "GET",
    "headers": {
      "X-VN-Auth-Token": "{{ secrets.VN_PAYROLL_TOKEN }}"
    }
  }
}

url은 들어오는 페이로드를 대상으로 평가되는 JSONata 표현식이고, {{ secrets.VN_PAYROLL_TOKEN }}은 암호화된 워크스페이스 시크릿에 대한 참조입니다. 시크릿은 요청이 플랫폼을 떠나는 시점에만 해석되므로, 토큰은 워크플로 정의에 결코 나타나지 않습니다. gateway는 HTTP(GET, POST, PUT, DELETE)로 통신하며 응답을 response.statusCode와 response.body로 돌려줍니다. JSON 본문은 파싱된 상태로 오고, 그 밖의 것은 원시 문자열로 옵니다. 그 응답을 해석하는 일(무엇을 "승인"으로 볼지 결정하고, 오류 코드를 꺼내는 일)은 JSONata로 작성된 다운스트림 TRANSFORMATION 단계의 몫입니다.

"커넥터 로직"을 구성으로 옮기면 공급자마다 맞춤형 마이크로서비스를 둘 필요가 없어집니다. 시크릿 주입과 일시적 장애의 재시도는 엔진이 처리합니다. 여러분은 "좌표"만 제공하면 됩니다.

범용 웹훅 수집: 명세가 없다고요? 문제없습니다

웹훅 수집은 인터넷의 무법지대입니다. 공급자마다 데이터를 보내는 방식이 제각각입니다.

엣지에서의 정규화

SchemaBridge의 entry point(워크플로를 시작하는 웹훅 URL)는 설계부터 스키마리스입니다. 사전에 선언된 스키마 없이 어떤 JSON 객체 본문이든 받아들입니다.

1. 계약 없는 수집: 본문은 있는 그대로 저장됩니다(요청 헤더는 호출을 인증하는 데에만 사용됩니다). 엣지에서는 어떤 스키마로도 검증하지 않으므로, 공급자가 필드를 추가하거나 이름을 바꿔도 이벤트가 거부되지 않습니다("쓰기 시점 검증"의 취약함을 피합니다).

2. 지연 변환: JSONata를 사용해 워크플로 라우팅에 필요한 특정 필드만 추출합니다.

솔직히 말하면 한계가 하나 있습니다. 본문은 JSON이어야 합니다. XML이나 폼 인코딩 데이터를 보내는 공급자라면, entry point 앞에 원시 페이로드를 JSON 봉투로 감싸는 작은 릴레이가 필요합니다.

양방향 브리지: "수신 확인 후 조회" 패턴

많은 롱테일 공급자는 불투명한 웹훅을 보냅니다. 무언가가 일어났다고는 알려 주지만, 무엇이 일어났는지는 알려 주지 않습니다. 받는 웹훅은 { "event": "order_updated", "id": 12345 } 같은 형태입니다. 실제 데이터를 얻으려면 그쪽 API를 다시 호출해야 합니다.

이것을 스크립트로 직접 만들면 경쟁 상태와 고아 이벤트가 생기기 쉽습니다.

SchemaBridge는 이것을 영속적인 라이프사이클로 만듭니다.

1. Entry Point(인바운드): ID가 담긴 웹훅을 받아 실행(run)의 시작으로 영속화합니다.

2. Delay(선택): 영속적인 DELAY 단계(예: delaySeconds: 5)로 공급자 측이 일관된 상태가 될 시간을 줍니다.

3. Gateway(아웃바운드): 공급자의 API를 호출해 전체 객체를 가져옵니다.

엔진이 이를 오케스트레이션하므로, "조회" 호출에서 일시적 장애(5xx, 429, 네트워크 오류)가 발생하면 지수 백오프로 재시도되며, 공급자가 과부하 상태라면 그 뒤에 수용 제어를 거쳐 몇 번 더 재디스패치됩니다(maxAutoRetries, 기본값 3). 그 이후에도 공급자가 계속 다운되어 있으면 실행은 눈에 보이게 실패하며, 원래 웹훅 페이로드는 영속화된 채로 남습니다. 공급자가 복구되면 실패한 단계부터 재시도할 수 있습니다. 전통적인 스크립트라면 그냥 죽고 원래 이벤트를 잃어버렸을 것입니다.

범용 커넥터를 위한 전문가 체크리스트

롱테일 공급자를 위한 범용 어댑터를 만들 때는 다음 기능을 확인하세요.

1. 인증 유연성: 커스텀 헤더, 암호화된 저장소에서의 시크릿 주입, 주기적으로 바뀌는 토큰을 처리할 수 있는가?

2. 포맷 허용성: 공급자가 JSON이 아닌 것을 반환할 때, 파서 크래시 대신 원시 응답에 접근할 수 있는가?

3. 지연 바인딩: JSONata 같은 언어로 수집 이후에 데이터를 매핑할 수 있는가?

4. 재시도와 복구: 일시적 장애가 자동으로 재시도되는가? 장애가 재시도보다 오래 지속될 때, 나중에 그 단계를 다시 실행할 수 있도록 이벤트가 보존되는가?

5. 감사 가능성: 조사가 필요할 때, 자격 증명을 워크플로 정의에 기록하지 않고도 실제 호출의 요청과 원시 응답을 확인할 수 있는가?

결론: API 배제의 종말

연결된 세상에서 어떤 공급자도 통합하기에 "너무 작거나" "너무 오래된" 존재여서는 안 됩니다. 맞춤 코딩된 래퍼에서 구성 가능한 범용 커넥터로 옮겨 감으로써, 우리는 SaaS 롱테일의 진입 장벽을 없앱니다. 기반 API가 아무리 파편화되어 있어도 전체 생태계를 하나의 시각적 상태로 연결하는 힘을 얻게 됩니다. "롱테일"을 부채에서 자산으로 바꾸는 것입니다.

같은 논리가 이제 에이전트에도 적용됩니다. 기존 API로 MCP 서버를 구축하는 방법을 참고하세요.

"Building the Bridge" 시리즈의 관련 글: 컴플라이언스와 감사.

살펴보기