업무 시스템에 계약이 들어오면 흐름이 갑자기 시스템 밖으로 새어 나가요. 계약서를 PDF로 만들어 메일로 보내고, 상대가 인쇄·서명·스캔해서 회신하길 기다리고, 받은 파일을 다시 폴더에 정리하죠. 시스템 안에서는 "계약 발송함" 다음이 비어 있어요. 그 사이가 전부 사람 손이에요.
행사·캐스팅 에이전시 CRM에서는 이 구간을 전자계약(모두싸인)으로 통합했어요. 이 글은 외부 e-sign 서비스를 업무 시스템에 붙일 때의 설계 포인트예요.
발송은 API로, 상태는 웹훅으로
전자계약 연동은 두 방향으로 나눠서 보면 깔끔해요.
- 내보내기(발송): 시스템이 계약 데이터를 모아 전자계약 API로 서명 요청을 보내요. 우리가 능동적으로 호출하는 쪽이에요.
- 들여오기(상태): 상대가 서명하면 그 사실을 시스템이 알아야 해요. 이건 우리가 계속 물어보는(polling) 대신, 전자계약 쪽이 알려주는 웹훅으로 받아요.
이 두 방향을 분리해서 생각하면 "언제 무엇을 호출하고, 무엇을 기다리는지"가 명확해져요.
폴링으로도 상태를 알아낼 수는 있어요. 몇 분마다 "이 계약 서명됐나요?"를 물어보면 되니까요. 하지만 이 방식은 두 가지를 갉아먹어요. 하나는 지연이에요. 서명이 끝나고 다음 폴링 주기까지는 시스템이 그 사실을 몰라요. 다른 하나는 낭비예요. 대부분의 조회는 "아직 서명 안 됨"이라는 똑같은 답만 반복해서 받아오는 헛수고예요. 계약 건수가 늘어날수록 이 헛수고도 그만큼 늘어나고요. 반면 웹훅은 상태가 바뀐 순간에만 딱 한 번 알려줘요.
웹훅은 검증과 멱등성이 전부예요
웹훅은 외부에서 우리 시스템으로 들어오는 입구라, 두 가지를 반드시 챙겨야 해요.
첫째, 서명 검증이에요. 들어온 요청이 진짜 전자계약 서비스가 보낸 게 맞는지 확인하지 않으면, 누구나 "서명 완료됐다"고 위조할 수 있어요. 그래서 요청에 담긴 서명을 공유 시크릿으로 검증해요.
둘째, **멱등성(idempotency)**이에요. 웹훅은 같은 이벤트를 여러 번 보낼 수 있어요(네트워크 재시도 때문에요). 같은 "서명 완료"가 두 번 와도 계약을 두 번 완료 처리하면 안 돼요. 그래서 이벤트를 받으면 현재 상태를 보고, 이미 처리된 거면 조용히 넘겨요.
웹훅이 아예 오지 않는 경우도 대비해야 해요. 전자계약 서비스 쪽 장애나 네트워크 문제로 웹훅이 유실될 수 있어서, 웹훅만 유일한 진실 공급원으로 삼기보다는 주기적으로 문서 상태를 다시 확인하는 보정 절차를 함께 두는 게 좋아요. 웹훅은 "빠른 경로", 보정 조회는 "느리지만 확실한 안전망"으로 역할을 나누는 셈이에요.
서명을 검증하고, 이미 처리된 이벤트는 조용히 넘겨 중복 처리를 막습니다
상태는 '계약'이 아니라 '문서'를 따라가요
연동에서 헷갈리기 쉬운 게, 우리 도메인의 "계약"과 전자계약 서비스의 "문서"를 1:1로 묶는 거예요. 외부 문서 ID를 우리 계약 레코드에 저장해두면, 웹훅이 문서 ID로 들어와도 어떤 계약인지 바로 찾을 수 있어요. 서명 완료 후 최종 PDF도 이 ID로 받아와 시스템에 보관해요. 그러면 "계약 발송함" 다음 칸이 더 이상 비어 있지 않아요. 발송·서명 대기·완료가 전부 시스템 안에 남죠.
이 매핑을 가볍게 여기면 나중에 값비싼 대가를 치러요. 예를 들어 "재발송"이 필요할 때, 새 문서를 만들면서 기존 계약 레코드와의 연결을 갱신하지 않으면 웹훅이 옛 문서 ID로 들어오는 순간 어떤 계약인지 찾지 못해요. 그래서 외부 문서 ID는 계약의 부가 정보가 아니라, 계약과 문서를 잇는 키로 다뤄야 해요.
또 하나 유의할 점은, 계약 하나에 서명자가 여러 명인 경우예요. 이런 계약은 "발송함"과 "완료됨" 사이에 "일부만 서명함" 같은 중간 상태가 생겨요. 이 중간 상태를 무시하고 완료 여부만 이분법으로 보면, 절반만 서명된 계약을 완료로 착각하거나 반대로 계속 대기 중으로 오해할 수 있어요. 문서 하나의 상태를 있는 그대로 따라가되, 그 상태가 우리 도메인에서 무엇을 의미하는지는 우리가 명시적으로 정의해둬야 해요.
정리
전자계약 연동의 핵심은 화려한 API가 아니라, 발송과 상태를 분리하고, 웹훅을 검증·멱등하게 받는 기본기예요. 이걸 갖추면 계약 흐름이 시스템 밖으로 새지 않아요. 서명이 끝난 계약은 자연스럽게 다음 단계인 정산으로 이어지는데, 그 자동화는 출연료 정산을 자동화한 방법에서 다뤄요. 전체 그림은 맞춤형 CRM 구축 사례에서 볼 수 있어요.
자주 묻는 질문
전자계약을 붙이면 기존 계약 흐름을 다 바꿔야 하나요?
아니요. 계약 데이터는 그대로 두고 "발송" 동작만 전자계약 API 호출로 바꾸면 됩니다. 외부 문서 ID를 계약 레코드에 저장해 상태만 연결하는 방식이라 기존 구조를 크게 건드리지 않아요.
웹훅을 놓치면 상태가 어긋나지 않나요?
웹훅 처리를 멱등하게 만들고, 필요하면 주기적으로 문서 상태를 조회해 보정하는 안전망을 둡니다. 같은 이벤트가 중복으로 와도 한 번만 반영되므로 재시도가 안전해요.
서명 완료된 계약서 원본은 어디에 보관되나요?
서명이 끝나면 최종 PDF를 외부 문서 ID로 내려받아 시스템에 보관합니다. 발송·서명 대기·완료·원본 보관이 모두 시스템 안에서 추적됩니다.