웹훅
계약 상태가 바뀌면 싸인딜이 등록한 주소로 알려 줘요. 연동 종류는 webhook, slack, telegram, notion, gsheet이고, 이 페이지는 범용 웹훅(webhook) 이야기예요. 아래 내용은 app/src/lib/integrations.ts에서 읽은 사실만 적었어요.
이벤트
contract.sentcontract.completedcontract.voidedcontract.declinedintegration.test
요청 헤더
| 헤더 | 뜻 |
|---|---|
x-signdeal-event | 이벤트 이름 |
x-signdeal-event-id | 이벤트 고유 번호(재시도해도 같아요). 받는 쪽이 중복을 걸러 낼 때 써요. |
x-signdeal-signature | 비밀값(secret)을 정했을 때만 와요. sha256=<hex> 모양의 HMAC-SHA256 서명이에요. |
서명 확인
서명은 요청 본문 문자열 그대로를 비밀값으로 HMAC-SHA256 한 값이에요. 본문을 다시 직렬화하지 말고 받은 그대로 계산하세요.
// Node.js 예시
import { createHmac, timingSafeEqual } from 'node:crypto';
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
// 헤더 x-signdeal-signature 와 같은지 비교
예시 본문(코드의 buildPayload로 만든 값)과, 비밀값 whsec_example로 계산한 서명이에요.
{
"event_id": "evt_ct_example_contract_sent",
"event": "contract.sent",
"occurred_at": "2026-01-01T00:00:00.000Z",
"service": "signdeal",
"contract": {
"id": "ct_example",
"tracking_id": "trk_example",
"client_ref": "order-0001",
"title": "예시 계약",
"contract_type": "service",
"status": "sent",
"sender_display_name": "(주)예시",
"recipients": [
{
"name": "홍길동",
"phone_masked": "010-****-0000"
}
],
"sent_at": "2026-01-01T00:00:00.000Z",
"completed_at": null,
"app_url": "https://app.signdeal.kr/app/contracts/ct_example",
"document": {
"final_pdf_available": false,
"final_pdf_api_path": "/api/contracts/ct_example/pdf?strict_final=1"
}
}
}
x-signdeal-signature: sha256=4520177165e92fba58d5310b7cbaec7ae063af7ffc227cc5512bed8336fc5530
서명은 위 JSON을 줄바꿈 없이 직렬화한 문자열 기준이에요.
재시도
보내기에 실패하면 이벤트는 먼저 저장돼 있다가 다시 시도해요. 시도 간격은 코드에 이렇게 들어 있어요: 1분 → 5분 → 30분 → 2시간 → 12시간. 그 뒤에는 마지막 간격(12시간)을 써요. 바깥 호출은 10초 안에 응답이 없으면 실패로 쳐요. 리다이렉트 응답(3xx)은 실패로 쳐요.
개인정보
받는 사람 휴대폰은 마스킹된 값(phone_masked)만 보내요. 원문 번호는 어떤 채널에도 보내지 않아요.