Wigo를 제품에 통합하기

회원이 사용 중인 시스템 안에서 바로 웹사이트를 만들 수 있게 하세요. 사용자 생성, 싱글 사인온 로그인, 사이트 생성/게시, 변경 시 webhook 수신을 지원합니다. OpenAPI 3 사양을 내려받아 클라이언트를 생성할 수 있습니다.

빠른 시작 (5분)

  1. 파트너로 등록하세요(인증된 이메일 필요) — 즉시 샌드박스에 진입하고 wgk_test_… 키를 받습니다(한 번만 표시되므로 반드시 저장하세요).
  2. 호출해 보기:
curl https://trywigo.com/v1/ping \
  -H "Authorization: Bearer wgk_test_xxxxxxxx"
  1. 사용자를 생성하고 로그인 링크를 받아 사용자를 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(사용자 수와 시트 수).

계정 보안: 이미 독립된 Wigo 계정이 있는 이메일은 거부됩니다(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.removedAPI를 통해 사용자가 생성/제거될 때
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":"…"} 형식으로 반환됩니다:

HTTPerror의미
400bad_request, bad_url, bad_redirect잘못된 데이터
401missing, invalid키 없음/잘못됨/폐기됨
403suspended, not_live파트너 정지됨 / 프로덕션 키 미활성화
404not_found사용자/사이트를 찾을 수 없음(또는 다른 파트너 소속)
409email_in_use, seat_limit, user_limit, site_limit, no_webhook충돌 / 할당량 초과
429—키당 분당 120회 초과

변경 내역

연동 지원이 필요하신가요: [email protected].