ConnectWiz + API와 Webhook

운영 중인 연동

저희가 파는 API가 저희가 쓰는 API입니다

플랫폼 전체가 OpenAPI 계약 하나에 명세돼 있고, 저희 패널과 모바일 앱도 그 파일에서 생성됩니다. 숨은 엔드포인트도, 문서와 실제의 어긋남도 없습니다. 그 위에 적용 범위를 지정한 Commerce API 키, 보호된 Webhook 트리거, 자사 시스템을 호출하는 플로우가 올라갑니다.

무료로 시작하기 모든 연동
OpenAPI 계약 하나 적용 범위를 지정한 API 키 HMAC으로 검증하는 Webhook
API와 Webhook × ConnectWiz
페이로드는 데이터일 뿐, 명령이 아닙니다
적용 범위 지정 키: 카탈로그 읽기 · 주문 쓰기
Webhook → HMAC 검증 → 플로우 시작
플로우 REST 스텝이 자사 API를 호출
1
기준이 되는 OpenAPI 계약 — 저희 패널과 모바일 앱이 생성되는 바로 그 파일입니다
3
Commerce 적용 범위 — 카탈로그 읽기, 주문 읽기, 주문 쓰기 — 키마다 발급합니다
100
한 번 읽을 때 최대 행 수, 서버에서 강제합니다 — limit 파라미터는 검증 대상이지 신뢰 대상이 아닙니다
50
API로 처리하는 주문당 품목 수 — 부딪혀서 알게 되는 한계가 아니라 미리 밝힌 한계입니다

개발자

하는 일, 정확히

기준이 되는 계약 하나

OpenAPI 3 문서 하나가 플랫폼을 명세하고, 저희 TypeScript 클라이언트가 거기서 생성됩니다. 실제가 문서에서 만들어지기 때문에 문서가 실제와 어긋날 수가 없습니다.

Commerce API 키

테넌트가 발급하는 키에 카탈로그 읽기, 주문 읽기, 주문 쓰기라는 적용 범위를 명시합니다. 이 키로 자사 스토어프런트나 앱을 같은 주문 엔진 위에서 돌릴 수 있고, 가격은 언제나 서버에서 결정됩니다.

수신 Webhook 보호

모든 플로우 Webhook 트리거는 고유한 URL과 시크릿을 가지고, 원문 바디에 대한 HMAC 검증과 리플레이 방지가 걸립니다. 페이로드는 사람을 지목할 수는 있어도 플로우 내부를 조종할 수는 없습니다.

발신은 플로우로

REST 스텝이 캔버스에 그려 둔 바로 그 순간에 자사 시스템을 호출합니다. 주문 생성, 동의 획득, 예약 완료 같은 순간들입니다.

기술적인 구조

API 설계 원칙을 밝힙니다

가격은 절대 클라이언트에서 오지 않습니다

주문 요청은 무엇을 몇 개인지만 말합니다. 이름과 가격은 그 시점에 서버에서 카탈로그를 읽어 와 스냅샷으로 품목에 기록합니다. 조작된 요청이 할인을 지어낼 수 없습니다.

호출하기 전에 지원 여부부터

각 연동 화면은 지원 기능 계약을 공개합니다. 전화번호로 매칭할 수 있는지, 비회원 주문을 나열할 수 있는지, 주문을 만들 수 있는지 같은 것들입니다. 명시된 “아니요”를 넘어 호출하면 저 깊은 곳에서 실패하는 대신 그 자리에서 예외가 납니다.

뜻이 있는 오류

전송 계층은 “권한 없음”과 “서비스 다운”을 구분합니다. 그래서 “상점에 닿을 수 없음”이 “이 고객은 구매한 적이 없음”으로 표시되는 일이 없습니다. 이름 붙은 오류가 API와 추측 게임을 가릅니다.

리플레이를 막는 Webhook

수신되는 모든 이벤트는 처리되기 전에 멱등 원장에서 고유 키를 선점합니다. 재시도되거나 재생된 전달은 자사 자동화가 아니라 데이터베이스 단에서 죽습니다.

키는 해시로, 시크릿은 범위 안에

API 키는 해시로 저장하고, 문 앞에서는 해시와 적용 범위만 해석됩니다. 유출된 데이터베이스 한 줄은 어느 워크스페이스인지도 말해 주지 않고, 그 적용 범위 밖의 무엇도 열지 못합니다.

초안인지 확정인지 명시합니다

주문 생성에는 명시적인 confirm 파라미터가 있습니다. 공개 API의 기본값은 확정이고, 패널 플로우는 초안으로 세워 둘 수 있습니다. 그래서 “이건 진짜인가?”가 관행이 아니라 필드입니다.

설정

연결 방식

01

키 발급

패널에서 적용 범위를 지정한 Commerce API 키를 만드세요. 해지도 그만큼 간단합니다.

02

Webhook 연결

Webhook 트리거가 달린 플로우를 만들고, 그 시크릿으로 요청에 서명하세요.

03

바깥으로 호출

자사 시스템이 알아야 할 지점에 REST 스텝을 넣으세요.

함께 쓰면 강해집니다

함께 쓰는 기능

Flows

Webhook 트리거가 플로우를 시작하고, REST 스텝이 캔버스에 그려 둔 순간마다 자사 시스템을 다시 호출합니다. 수신 자동화와 발신 자동화가 캔버스 하나를 함께 씁니다.

Commerce

API 뒤에서 도는 것은 카탈로그와 주문 엔진 — 채팅 숍과 AI가 쓰는 바로 그 엔진입니다. 주문의 진실은 하나, 문은 넷입니다.

자사 스토어프런트

팀들은 이미 Commerce API 위에서 헤드리스 스토어프런트를 운영합니다. Shopify 페이지 권장 경로가 바로 이것입니다. 네이티브 커넥터가 만들어지는 동안의 경로라고 그 페이지에 솔직하게 적어 두었습니다.

보안과 보증

지루한 보증

원문 바디에 대한 HMAC

Webhook 검증은 트리거별 시크릿으로 원문 요청 바디에 서명하고 상수 시간으로 비교합니다. 파싱은 증명이 끝난 뒤에야 일어납니다.

페이로드는 데이터일 뿐, 명령이 아닙니다

Webhook 페이로드는 사람을 가리킬 수는 있지만, 플로우 내부를 조종하거나 프롬프트를 고쳐 쓰거나 도구를 호출할 수는 없습니다. 데이터와 지시 사이의 경계는 동작이 아니라 구조로 그어져 있습니다.

모든 문에 속도 제한

공개 엔드포인트에는 표준 스로틀링이 걸리고, 읽기 한도는 서버에서 강제됩니다. 잘못 동작하는 클라이언트는 플랫폼이 아니라 자기 자신을 느리게 만듭니다.

솔직한 세부 조건

경계를 명시합니다

아직 파이어호스는 없습니다

전부 구독하는 범용 Webhook 피드는 만들어져 있지 않습니다. 지금 발신 이벤트는 플로우 스텝으로 나갑니다. 어떤 영업 통화에서도 돌려 말할 필요가 없도록 여기에 적어 둡니다.

읽기에 한계를 둔 것은 설계입니다

읽기는 커서와 함께 최대 100행을 반환합니다. 이 API는 대량 내보내기가 아니라 운영 연동을 위해 만들었습니다. 대량 처리가 필요하면 우회로가 아니라 대화로 풀어야 합니다.

API와 Webhook FAQ

솔직한 답변

더 자세한 내용은 FAQ에서 확인하시거나, 직접 문의해 주세요.

플랫폼은 OpenAPI 3 계약 하나에 명세돼 있고, 저희 웹 패널과 모바일 앱이 타입을 생성하는 파일도 같은 것입니다. 연동하시는 대상이 곧 저희가 돌리는 대상입니다.

트리거별 시크릿, 원문 바디에 대한 HMAC 검증, 멱등 원장을 통한 리플레이 방지가 있습니다. 그리고 원칙상 페이로드는 데이터입니다. 사람을 가리킬 수는 있어도 자동화에 명령할 수는 없습니다.

플로우 REST 스텝으로, 캔버스에서 고르신 순간에 발사됩니다. 범용 발신 Webhook 피드는 로드맵에 있고, 출시 전까지는 일부러 약속하지 않습니다.

네. 카탈로그 읽기와 주문 쓰기가 지원되는 경로이고, 가격은 서버에서 결정되며, 키는 화면 단위로 해지할 수 있습니다. 품목 50개, 행 100개라는 한계는 부딪히기 전에 설계에 반영하시라고 미리 밝혀 둡니다.

저희 쪽 전달은 멱등합니다. 원장이 재생을 알아보고 버리기 때문에 자사 시스템이 안전하게 재시도할 수 있습니다. 플로우에서 나가는 REST 스텝은 자체 재시도 정책을 가지고, 실패는 플로우 실행 기록에 드러납니다.

요란한 연동보다 정직한 연동이 낫습니다.

여기 있는 연동은 하나같이 실제 동작 그대로 설명합니다. 데이터가 흐르는 방향, 소유권, 한계까지 빠짐없이 적었습니다.

무료로 시작하기 모든 연동