스노우싸인 웹훅(Webhook) 가이드
목차
개요
웹훅을 통해 계약 관련 이벤트를 실시간으로 수신할 수 있습니다. 이벤트 발생 시 등록된 URL로 HTTP POST 요청이 전송됩니다.
| 항목 | 값 |
|---|---|
| HTTP 메서드 | POST |
| 타임아웃 | 5초 |
| 성공 판정 | HTTP 2xx 응답 |
| 서명 방식 | HMAC-SHA256 |
| 실패 시 | 일시적 오류 자동 재시도, 로그·수동 재전송 제공 |
웹훅 설정
웹훅 생성
- 스노우싸인 웹 콘솔 → 조직 설정 → 웹훅
- 새 웹훅 추가 클릭
- 이름, 수신 URL (HTTPS 권장), 구독할 이벤트 입력
- 저장 후 시크릿 키 안전하게 보관
⚠️ 시크릿 키는 최초 생성 시에만 표시됩니다. 분실 시 재생성이 필요합니다.
웹훅 테스트
설정 후 테스트 버튼을 클릭하면 테스트 페이로드가 발송됩니다:
{
"id": "webhook-event-uuid",
"event": "test",
"timestamp": "2025-01-06T10:00:00",
"data": {
"message": "This is a test webhook event"
}
}시크릿 재생성
시크릿 키 노출 또는 분실 시: 웹훅 설정 → 시크릿 재생성 → 새 키 확인 후 서버 측 업데이트
이벤트 타입
| 이벤트 | 설명 | 발생 시점 |
|---|---|---|
contract.sent | 계약 발송/활성화됨 | 참여자별로 계약이 발송되거나 서명 링크를 사용할 수 있게 될 때 |
contract.viewed | 계약서 열람됨 | 참여자가 처음 열람할 때 |
participant.signed | 참여자 서명 완료 | 개별 참여자가 서명할 때 |
participant.declined | 참여자 서명 거절 | 참여자가 서명을 거절할 때 |
contract.completed | 모든 서명 완료 | 모든 참여자 서명 완료 시 |
contract.cancelled | 계약 취소됨 | 발송자가 취소하거나, 서명 대기 중인 계약서를 휴지통으로 옮길 때 |
contract.expired | 계약 만료됨 | 만료일 경과 시 |
participant.revision_requested | 수정 요청됨 | 참여자가 서명 대신 수정을 요청할 때(서명 일시 중지) |
contract.revised | 수정본 발송됨 | 발송자가 수정본을 보낼 때(같은 링크로 다시 서명) |
contract.signing_resumed | 서명 재개됨 | 발송자가 수정 없이 서명을 이어 갈 때 |
위 10개 이벤트 중 1개 이상을 선택해야 합니다. 미지원 이벤트는 거부되며 중복값은 한 번만 저장됩니다.
이메일 전달 실패·반송·수신거부는 고객 웹훅으로 발행하지 않습니다. 계약 생성자 알림 이메일 또는 Public API의 계약 목록·상세·상태 조회로 확인하세요.
권장 구독 조합:
- 필수:
contract.completed,contract.cancelled - 선택:
contract.sent,contract.viewed,participant.signed,participant.declined - 외부 전달 계약(
dispatch_mode=external): 수정 이벤트 3종. 이 계약의 참여자에게는 스노우싸인이 수정 안내를 보내지 않습니다.
페이로드
공통 구조
{
"id": "webhook-event-uuid",
"event": "이벤트_타입",
"timestamp": "2025-01-06T10:00:00",
"data": { }
}id는 이벤트의 고유 ID이며 자동·수동 재전송에도 바뀌지 않습니다. timestamp와 *_at 시각 필드는 UTC 기준입니다. 계약 이벤트의 data에는 contract_id, title, dispatch_mode, responsible_permission_group: { uuid, name }이 포함됩니다.
참여자 정보에는 participant_id, name, email, phone, signing_order, security_method가 포함되며 이메일은 없을 수 있습니다.
security_method는 email, phone, password, identity_verification 중 하나입니다. phone은 계약 요청자가 입력한 연락처입니다.
링크서명 완료 시 participant.signed 다음 contract.completed가 발행됩니다. 두 이벤트의 data에만 다음 참조가 추가되며 링크 토큰과 URL은 포함되지 않습니다. 링크 생성·일시중지·재개·종료·만료 이벤트는 제공하지 않습니다.
{ "link_signing": { "id": "link-signing-uuid", "name": "입사 동의서" } }수정 이벤트의 revision_number는 상대방에게 보이는 차수(처음 발송본이 1)입니다. body·summary·reply는 비어 있으면 null입니다. notified_participants는 스노우싸인이 수정본 안내를 보낸 참여자, requesters는 수정을 요청했던 참여자입니다. 수정본을 보내면 참여자 입력값이 비워지고 같은 링크로 다시 서명하며, 결재가 필요하면 최종 승인 때 contract.revised가 발행됩니다.
HTTP 헤더
| 헤더 | 설명 |
|---|---|
| Content-Type | application/json |
| X-Webhook-Event | 이벤트 타입 |
| X-Webhook-Signature | HMAC-SHA256 서명 |
contract.sent
{
"id": "webhook-event-uuid",
"event": "contract.sent",
"timestamp": "2025-01-06T10:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"sent_at": "2025-01-06T10:00:00",
"expires_at": "2025-01-31T23:59:59",
"participants": [
{ "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" },
{ "participant_id": "participant-uuid-2", "name": "김철수", "email": "kim@example.com", "phone": null, "signing_order": 2, "security_method": "password" }
]
}
}contract.viewed
{
"id": "webhook-event-uuid",
"event": "contract.viewed",
"timestamp": "2025-01-06T11:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"participant": { "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" },
"viewed_at": "2025-01-06T11:00:00"
}
}participant.signed
{
"id": "webhook-event-uuid",
"event": "participant.signed",
"timestamp": "2025-01-06T14:30:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"participant": { "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" },
"signed_at": "2025-01-06T14:30:00",
"all_signed": false,
"signed_count": 1,
"total_count": 2
}
}링크서명은 참여자가 한 명이므로 all_signed=true, signed_count=1, total_count=1입니다.
participant.declined
{
"id": "webhook-event-uuid",
"event": "participant.declined",
"timestamp": "2025-01-06T14:30:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"participant": { "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" },
"reason": "계약 조건에 동의하지 않습니다.",
"declined_at": "2025-01-06T14:30:00"
}
}contract.completed
{
"id": "webhook-event-uuid",
"event": "contract.completed",
"timestamp": "2025-01-06T15:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"completed_at": "2025-01-06T15:00:00",
"participants": [
{ "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone", "signed_at": "2025-01-06T14:30:00" },
{ "participant_id": "participant-uuid-2", "name": "김철수", "email": "kim@example.com", "phone": null, "signing_order": 2, "security_method": "password", "signed_at": "2025-01-06T15:00:00" }
],
"download_url": "https://..."
}
}
download_url은 서명된 계약서 PDF의 1시간 유효 임시 URL입니다. 완료 PDF가 없거나 URL 생성에 실패하면 null일 수 있습니다. 필요한 경우 Public API에서 새 URL을 조회합니다.
contract.cancelled
{
"id": "webhook-event-uuid",
"event": "contract.cancelled",
"timestamp": "2025-01-06T12:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"cancelled_at": "2025-01-06T12:00:00",
"reason": "고객 요청으로 취소"
}
}서명 대기 중인 계약서를 휴지통으로 옮겨 취소하면
reason은 null이며, 이후 Public API로 이 계약서를 조회하면 404를 반환합니다.
contract.expired
{
"id": "webhook-event-uuid",
"event": "contract.expired",
"timestamp": "2025-01-31T23:59:59",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"expired_at": "2025-01-31T23:59:59"
}
}participant.revision_requested
{
"id": "webhook-event-uuid",
"event": "participant.revision_requested",
"timestamp": "2025-01-07T09:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"participant": { "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" },
"body": "제3조 지급일을 말일로 바꿔주세요.",
"requested_at": "2025-01-07T09:00:00"
}
}contract.revised
{
"id": "webhook-event-uuid",
"event": "contract.revised",
"timestamp": "2025-01-07T14:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"revision_number": 2,
"summary": "제3조 대금 지급일 변경",
"expires_at": "2025-01-31T23:59:59",
"revised_at": "2025-01-07T14:00:00",
"notified_participants": [
{ "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" }
]
}
}contract.signing_resumed
{
"id": "webhook-event-uuid",
"event": "contract.signing_resumed",
"timestamp": "2025-01-07T11:00:00",
"data": {
"contract_id": "uuid-string",
"title": "업무 위탁 계약서",
"dispatch_mode": "external",
"reply": "현재 내용으로 진행 부탁드립니다.",
"resumed_at": "2025-01-07T11:00:00",
"requesters": [
{ "participant_id": "participant-uuid-1", "name": "홍길동", "email": null, "phone": "010-1234-5678", "signing_order": 1, "security_method": "phone" }
]
}
}서명 검증
모든 웹훅 요청에는 X-Webhook-Signature 헤더가 포함됩니다. 반드시 검증 후 처리하세요.
signature = HMAC-SHA256(시크릿_키, 요청_본문_raw_body)검증 순서:
X-Webhook-Signature헤더 추출- 수신한 요청 본문(raw body)을 파싱하거나 재직렬화하지 않고 그대로 시크릿 키로 HMAC-SHA256 해시
- 계산된 서명과 헤더 서명을 안전하게 비교 (timing-safe)
Python
import hmac
import hashlib
def verify_webhook(payload_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode('utf-8'),
payload_body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)JavaScript
const crypto = require('crypto');
function verifyWebhook(payloadBody, signature, secret) {
const expected = crypto
.createHmac('sha256', secret)
.update(payloadBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}수신 서버 가이드
핵심 원칙
- HTTPS 엔드포인트 사용
- 즉시 200 OK 응답 후 비동기로 이벤트 처리 (5초 타임아웃 초과 방지)
- 같은 이벤트가 다시 들어와도 한 번만 반영되도록 중복 처리
샘플 코드
Python (Flask)
import hmac
import hashlib
import logging
import os
from flask import Flask, request, jsonify
from queue import Queue
import threading
app = Flask(__name__)
WEBHOOK_SECRET = os.environ['SNOWSIGN_WEBHOOK_SECRET']
event_queue = Queue()
logger = logging.getLogger(__name__)
def verify_signature(payload: bytes, signature: str) -> bool:
expected = hmac.new(
WEBHOOK_SECRET.encode('utf-8'),
payload,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
def process_event(event_data):
event_type = event_data.get('event')
data = event_data.get('data', {})
if event_type == 'contract.completed':
logger.info('계약 완료: %s', data.get('contract_id'))
elif event_type == 'participant.signed':
logger.info('서명 완료: %s', data.get('participant', {}).get('name'))
def worker():
while True:
event_data = event_queue.get()
try:
process_event(event_data)
except Exception:
logger.exception('웹훅 이벤트 처리 오류')
event_queue.task_done()
threading.Thread(target=worker, daemon=True).start()
@app.route('/webhook/snowsign', methods=['POST'])
def webhook_handler():
signature = request.headers.get('X-Webhook-Signature', '')
if not verify_signature(request.data, signature):
return jsonify({'error': 'Invalid signature'}), 401
event_queue.put(request.json)
return jsonify({'received': True}), 200
if __name__ == '__main__':
app.run(port=5000)JavaScript (Express)
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = process.env.SNOWSIGN_WEBHOOK_SECRET;
app.use('/webhook', express.raw({ type: 'application/json' }));
function verifySignature(payload, signature) {
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET).update(payload).digest('hex');
try {
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
} catch {
return false;
}
}
app.post('/webhook/snowsign', (req, res) => {
const signature = req.headers['x-webhook-signature'];
if (!verifySignature(req.body, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const eventData = JSON.parse(req.body.toString());
setImmediate(() => {
switch (eventData.event) {
case 'contract.completed':
console.log(`계약 완료: ${eventData.data.contract_id}`);
break;
case 'participant.signed':
console.log(`서명 완료: ${eventData.data.participant?.name}`);
break;
}
});
res.json({ received: true });
});
app.listen(3000, () => console.log('Webhook server running on port 3000'));문제 해결
| 증상 | 확인 사항 |
|---|---|
| 웹훅 미수신 | URL이 HTTPS인지 확인, 방화벽 설정, 콘솔 로그에서 발송 상태 확인, 테스트 버튼으로 연결 확인 |
| 서명 검증 실패 | 올바른 시크릿 사용 중인지 확인, raw body (파싱 전 원본) 사용 여부 확인, 필요시 시크릿 재생성 |
| 중복 이벤트 수신 | payload의 id가 이미 처리됐는지 확인 |
최종 수정: 2026-09-04 문서 버전: 1.8