업무 시스템에 계약이 들어오면 흐름이 갑자기 시스템 밖으로 새어 나가요. 계약서를 PDF로 만들어 메일로 보내고, 상대가 인쇄·서명·스캔해서 회신하길 기다리고, 받은 파일을 다시 폴더에 정리하죠. 시스템 안에서는 "계약 발송함" 다음이 비어 있어요. 그 사이가 전부 사람 손이에요.
행사·캐스팅 에이전시 CRM에서는 이 구간을 전자계약(모두싸인)으로 통합했어요. 이 글은 외부 e-sign 서비스를 업무 시스템에 붙일 때의 설계 포인트예요.
발송은 API로, 상태는 웹훅으로
전자계약 연동은 두 방향으로 나눠서 보면 깔끔해요.
- 내보내기(발송): 시스템이 계약 데이터를 모아 전자계약 API로 서명 요청을 보내요. 우리가 능동적으로 호출하는 쪽이에요.
- 들여오기(상태): 상대가 서명하면 그 사실을 시스템이 알아야 해요. 이건 우리가 계속 물어보는(polling) 대신, 전자계약 쪽이 알려주는 웹훅으로 받아요.
이 두 방향을 분리해서 생각하면 "언제 무엇을 호출하고, 무엇을 기다리는지"가 명확해져요.
웹훅은 검증과 멱등성이 전부예요
웹훅은 외부에서 우리 시스템으로 들어오는 입구라, 두 가지를 반드시 챙겨야 해요.
첫째, 서명 검증이에요. 들어온 요청이 진짜 전자계약 서비스가 보낸 게 맞는지 확인하지 않으면, 누구나 "서명 완료됐다"고 위조할 수 있어요. 그래서 요청에 담긴 서명을 공유 시크릿으로 검증해요.
둘째, **멱등성(idempotency)**이에요. 웹훅은 같은 이벤트를 여러 번 보낼 수 있어요(네트워크 재시도 때문에요). 같은 "서명 완료"가 두 번 와도 계약을 두 번 완료 처리하면 안 돼요. 그래서 이벤트를 받으면 현재 상태를 보고, 이미 처리된 거면 조용히 넘겨요.
# 모두싸인 웹훅: 검증하고, 멱등하게 상태만 동기화
def create
verify_signature!(request) # 위조 차단
contract = Contract.find_by(external_id: params[:document_id])
contract.mark_signed! unless contract.signed? # 멱등
head :ok
end상태는 '계약'이 아니라 '문서'를 따라가요
연동에서 헷갈리기 쉬운 게, 우리 도메인의 "계약"과 전자계약 서비스의 "문서"를 1:1로 묶는 거예요. 외부 문서 ID를 우리 계약 레코드에 저장해두면, 웹훅이 문서 ID로 들어와도 어떤 계약인지 바로 찾을 수 있어요. 서명 완료 후 최종 PDF도 이 ID로 받아와 시스템에 보관해요. 그러면 "계약 발송함" 다음 칸이 더 이상 비어 있지 않아요. 발송·서명 대기·완료가 전부 시스템 안에 남죠.
정리
전자계약 연동의 핵심은 화려한 API가 아니라, 발송과 상태를 분리하고, 웹훅을 검증·멱등하게 받는 기본기예요. 이걸 갖추면 계약 흐름이 시스템 밖으로 새지 않아요. 서명이 끝난 계약은 자연스럽게 다음 단계인 정산으로 이어지는데, 그 자동화는 출연료 정산을 자동화한 방법에서 다뤄요. 전체 그림은 맞춤형 CRM 구축 사례에서 볼 수 있어요.
자주 묻는 질문
전자계약을 붙이면 기존 계약 흐름을 다 바꿔야 하나요?
아니요. 계약 데이터는 그대로 두고 "발송" 동작만 전자계약 API 호출로 바꾸면 됩니다. 외부 문서 ID를 계약 레코드에 저장해 상태만 연결하는 방식이라 기존 구조를 크게 건드리지 않아요.
웹훅을 놓치면 상태가 어긋나지 않나요?
웹훅 처리를 멱등하게 만들고, 필요하면 주기적으로 문서 상태를 조회해 보정하는 안전망을 둡니다. 같은 이벤트가 중복으로 와도 한 번만 반영되므로 재시도가 안전해요.
서명 완료된 계약서 원본은 어디에 보관되나요?
서명이 끝나면 최종 PDF를 외부 문서 ID로 내려받아 시스템에 보관합니다. 발송·서명 대기·완료·원본 보관이 모두 시스템 안에서 추적됩니다.