쉽게 연동하기

스노우싸인 웹훅(Webhook) 가이드

목차

개요

웹훅을 통해 계약 관련 이벤트를 실시간으로 수신할 수 있습니다. 이벤트 발생 시 등록된 URL로 HTTP POST 요청이 전송됩니다.

항목값
HTTP 메서드POST
타임아웃5초
성공 판정HTTP 2xx 응답
서명 방식HMAC-SHA256
실패 시일시적 오류 자동 재시도, 로그·수동 재전송 제공

웹훅 설정

웹훅 생성

  1. 스노우싸인 웹 콘솔 → 조직 설정 → 웹훅
  2. 새 웹훅 추가 클릭
  3. 이름, 수신 URL (HTTPS 권장), 구독할 이벤트 입력
  4. 저장 후 시크릿 키 안전하게 보관

⚠️ 시크릿 키는 최초 생성 시에만 표시됩니다. 분실 시 재생성이 필요합니다.

웹훅 테스트

설정 후 테스트 버튼을 클릭하면 테스트 페이로드가 발송됩니다:

json
{
  "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종. 이 계약의 참여자에게는 스노우싸인이 수정 안내를 보내지 않습니다.

페이로드

공통 구조

json
{
  "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은 포함되지 않습니다. 링크 생성·일시중지·재개·종료·만료 이벤트는 제공하지 않습니다.

json
{ "link_signing": { "id": "link-signing-uuid", "name": "입사 동의서" } }

수정 이벤트의 revision_number는 상대방에게 보이는 차수(처음 발송본이 1)입니다. body·summary·reply는 비어 있으면 null입니다. notified_participants는 스노우싸인이 수정본 안내를 보낸 참여자, requesters는 수정을 요청했던 참여자입니다. 수정본을 보내면 참여자 입력값이 비워지고 같은 링크로 다시 서명하며, 결재가 필요하면 최종 승인 때 contract.revised가 발행됩니다.

HTTP 헤더

헤더설명
Content-Typeapplication/json
X-Webhook-Event이벤트 타입
X-Webhook-SignatureHMAC-SHA256 서명

contract.sent

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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

json
{
  "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 헤더가 포함됩니다. 반드시 검증 후 처리하세요.

text
signature = HMAC-SHA256(시크릿_키, 요청_본문_raw_body)

검증 순서:

  1. X-Webhook-Signature 헤더 추출
  2. 수신한 요청 본문(raw body)을 파싱하거나 재직렬화하지 않고 그대로 시크릿 키로 HMAC-SHA256 해시
  3. 계산된 서명과 헤더 서명을 안전하게 비교 (timing-safe)

Python

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

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)

python
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)

javascript
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