Wigo를 제품에 통합하기
회원이 사용 중인 시스템 안에서 바로 웹사이트를 만들 수 있게 하세요. 사용자 생성, 싱글 사인온 로그인, 사이트 생성/게시, 변경 시 webhook 수신을 지원합니다. OpenAPI 3 사양을 내려받아 클라이언트를 생성할 수 있습니다.
빠른 시작 (5분)
- 파트너로 등록하세요(인증된 이메일 필요) — 즉시 샌드박스에 진입하고
wgk_test_…키를 받습니다(한 번만 표시되므로 반드시 저장하세요). - 호출해 보기:
curl https://trywigo.com/v1/ping \
-H "Authorization: Bearer wgk_test_xxxxxxxx"
- 사용자를 생성하고 로그인 링크를 받아 사용자를 Wigo로 보내기:
# 1) create/update a member (idempotent by external_id)
curl -X PUT https://trywigo.com/v1/users/member-123 \
-H "Authorization: Bearer $WIGO_KEY" -H "Content-Type: application/json" \
-d '{"email":"[email protected]","name":"Nguyễn Văn A"}'
# 2) ONE-TIME login link (expires in 60 seconds)
curl -X POST https://trywigo.com/v1/users/member-123/login-links \
-H "Authorization: Bearer $WIGO_KEY" -H "Content-Type: application/json" \
-d '{"redirect":"/#/my-site"}'
# → {"url":"https://trywigo.com/sso/…","expires_in":60} — redirect the user's browser to this url
인증
모든 /v1/* 요청에 헤더 Authorization: Bearer <key>를 포함하세요. 요청은 서버에서 보내야 합니다(키를 브라우저에서 실행되는 코드에 넣지 마세요). Wigo는 키의 해시만 저장합니다. 키를 분실하면 파트너 포털에서 폐기하고 새로 만드세요(모드당 최대 5개). 요청 제한: 키당 분당 120회.
샌드박스와 프로덕션
Sandbox (wgk_test_…) | Production (wgk_live_…) | |
|---|---|---|
| 발급 방법 | 직접 등록 후 즉시 사용 | 법인 정보 입력 → 프로덕션 신청 → Wigo 관리자 승인 → 시트 요금제 구매 |
| 사용자 권한 | 무료 체험 요금제와 동일(사이트 1개, AI 없음, 배지 + noindex, 자동 정리) | 해당 개인 요금제(Basic/Professional)와 동일. 사용자에게 결제 알림이 표시되지 않음 |
| 할당량 | 최대 50명 | 구매한 시트 수에 따름 |
두 모드는 완전히 분리되어 있습니다. 테스트 키로는 실제 사용자를 볼 수 없고, 그 반대도 마찬가지입니다.
사용자
PUT/v1/users/{external_id} — 생성 또는 업데이트. 본문: email(생성 시 필수), name, plan(basic|pro, 프로덕션 전용, 기본값은 사용 가능한 Professional 시트). 생성 시 201, 사용자가 이미 있으면 200을 반환합니다.
GET/v1/users/{external_id} · DELETE/v1/users/{external_id}(파트너에서 사용자를 제거: 시트가 반환되고, 권한이 만료되며, 사이트는 15/30/45일 만료 수명주기에 들어갑니다) · GET/v1/usage(사용자 수와 시트 수).
email_in_use). 파트너는 다른 사람의 계정을 가로챌 수 없습니다. API로 새로 생성된 사용자는 첫 방문 시 Wigo 약관에 동의해야 합니다.싱글 사인온(SSO)
POST/v1/users/{external_id}/login-links — {"url", "expires_in":60}을 반환합니다. 사용자를 url로 리디렉션하세요. Wigo가 링크를 로그인 세션으로 교환한 뒤 redirect(/#/path 형식, 기본값 /#/my-site)로 보냅니다. 링크는 일회용이며 60초 후 만료됩니다. 재사용되었거나 만료된 링크 ⇒ 안내 페이지가 표시됩니다. 파트너 검증은 API 키 자체로 이루어집니다.
사이트 및 게시
| 요청 | 설명 |
|---|---|
GET /v1/users/{external_id}/sites | 사용자의 사이트 목록 조회 |
POST /v1/users/{external_id}/sites | 사이트 생성: {"name":"Quán A","template":"quan-ca-phe"}(template은 선택). 요금제 한도에 도달하면 ⇒ 409 site_limit |
POST /v1/sites/{id}/deploy | 사이트 게시: {"subdomain":"quan-a"} ⇒ 202 {"job_id","version"}. 사이트는 https://quan-a.trywigo.com에서 운영되며 site.deployed webhook을 받습니다 |
Webhooks
HTTPS 주소를 파트너 포털 또는 PUT /v1/webhook {"url":"https://…"}로 설정하세요(서명 시크릿 whsec_…가 반환됩니다). POST /v1/webhook/test는 테스트 이벤트를 보냅니다. 내부 네트워크를 가리키는 주소는 거부됩니다. Wigo는 JSON POST를 보냅니다:
{ "id": "evt-uuid", "type": "site.deployed", "created": "2026-10-30T03:00:00Z", "livemode": false,
"data": { "user": { "external_id": "member-123", "email": "[email protected]" },
"site": { "id": "…", "name": "Quán A", "subdomain": "quan-a", "url": "https://quan-a.trywigo.com", "version": 1 } } }
| 이벤트 | 발생 시점 |
|---|---|
user.created · user.removed | API를 통해 사용자가 생성/제거될 때 |
user.entitlement_changed | 권한이 유효해지거나 중단될 때(갱신, 시트 소진, 파트너가 샌드박스로 되돌려짐) |
site.created · site.deployed · site.deleted | 사용자가 사이트를 생성/게시/삭제할 때 |
webhook.test | "테스트 보내기"를 클릭할 때 |
서명 검증
헤더 X-Wigo-Signature: t=<unix>,v1=<hex>. 여기서 v1 = HMAC-SHA256(secret, "<t>." + <raw body>)입니다. 서명은 원본 본문(raw body)으로 검증하고, t가 5분 넘게 차이 나면 요청을 거부하세요.
// Node.js
const crypto = require("crypto");
function verify(rawBody, header, secret) {
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}
# Python
import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
t, v1 = [p.split("=", 1)[1] for p in header.split(",")]
if abs(time.time() - int(t)) > 300: return False
mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
<?php // PHP
function verify(string $raw, string $header, string $secret): bool {
[$t, $v1] = array_map(fn($p) => explode("=", $p, 2)[1], explode(",", $header));
if (abs(time() - (int)$t) > 300) return false;
return hash_equals(hash_hmac("sha256", "$t.$raw", $secret), $v1);
}
전달: 수신 확인을 위해 10초 이내에 2xx 상태 코드로 응답하세요. 실패 시 1분 → 5분 → 30분 → 2시간 → 12시간 후에 재시도됩니다(최초 시도 포함 최대 6회). 파트너 포털에서 로그를 확인하고 "재전송"을 클릭할 수 있습니다. 이벤트는 중복되거나 순서가 바뀌어 도착할 수 있으므로 id 기준으로 멱등하게 처리하세요.
시트 및 권한 (프로덕션)
프로덕션 사용자 한 명당 시트 1개를 사용하며 해당 개인 요금제와 동일한 권한을 받습니다. 시트는 파트너 포털에서 연 단위로 구매합니다(최소 100시트, 구간별 할인). 시트가 소진되면 ⇒ 409 seat_limit. 시트가 만료되거나 파트너가 샌드박스로 되돌려지면 ⇒ 사용자는 user.entitlement_changed webhook(active:false)을 받고 만료 수명주기에 들어갑니다(15일 후 보기 전용, 30일 후 사이트 중지, 45일 후 정리). 사이트를 유지하려면 사용자가 직접 개인 요금제를 구매할 수 있습니다.
오류 및 제한
오류는 JSON {"error":"code","message":"…"} 형식으로 반환됩니다:
| HTTP | error | 의미 |
|---|---|---|
| 400 | bad_request, bad_url, bad_redirect | 잘못된 데이터 |
| 401 | missing, invalid | 키 없음/잘못됨/폐기됨 |
| 403 | suspended, not_live | 파트너 정지됨 / 프로덕션 키 미활성화 |
| 404 | not_found | 사용자/사이트를 찾을 수 없음(또는 다른 파트너 소속) |
| 409 | email_in_use, seat_limit, user_limit, site_limit, no_webhook | 충돌 / 할당량 초과 |
| 429 | — | 키당 분당 120회 초과 |
변경 내역
- v1(2026-10-30): 출시 — 사용자, SSO 로그인 링크, 사이트 + 게시, HMAC 서명 webhook, 샌드박스/프로덕션, 연 단위 시트.
연동 지원이 필요하신가요: [email protected].