개발자 가이드

SecureKey API 연동에 필요한 상세 가이드입니다.

Webhook 콜백

인증 완료 시 고객 서버로 HTTP POST 콜백을 자동 전송합니다.
API Key 생성 시 webhookUrl을 지정하면 HMAC 서명용 webhookSecret이 자동 생성됩니다. 이 값은 현재 구현상 API Key 생성 응답에서만 다시 확인할 수 있습니다.

이벤트 타입

event channel 설명
verification.completed sms SMS OTP 검증 성공
verification.completed email Email OTP 검증 성공
verification.completed totp TOTP 코드 검증 성공 (백업 코드 포함)
verification.completed webauthn 패스키 인증 성공
push.responded push Push 인증 승인 또는 거부
verification.session.completed session 검증 세션의 모든 요구 채널 완료

콜백 페이로드

POST (고객 서버로 전송)
{
  "event": "verification.completed",
  "channel": "sms",
  "data": {
    "requestId": "cuid...",
    "externalUserId": "user_123",
    "phone": "01012345678",
    "purpose": "login"
  },
  "timestamp": "2026-03-24T12:00:00+09:00"
}

HMAC 서명 검증

모든 webhook 요청에 X-SecureKey-Signature 헤더가 포함됩니다. 반드시 서명을 검증한 후 처리하세요.

서명 검증Node.js 
const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(body))
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature), Buffer.from(expected)
  );
}

// Express 미들웨어 예시
app.post('/webhook/securekey', (req, res) => {
  const sig = req.headers['x-securekey-signature'];
  if (!verifySignature(req.body, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // 인증 완료 처리
  const { event, channel, data } = req.body;
  console.log(`${channel} 인증 완료: ${data.externalUserId}`);
  res.sendStatus(200);
});
서명 검증Python 
import hmac, hashlib, json

def verify_signature(body: dict, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), json.dumps(body).encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

전송 정책

타임아웃 5초 (초과 시 전송 포기)
재시도 없음 (fire-and-forget, 실패 시 서버 로그에만 기록)
대상 제한 localhost, loopback, 사설 IP 대상 URL은 SSRF 방지 때문에 차단됩니다.
권장 Webhook은 보조 알림 용도로 활용하고, 핵심 검증 결과는 API 응답 또는 폴링으로 확인하세요.