싸인딜 개발자

웹훅

계약 상태가 바뀌면 싸인딜이 등록한 주소로 알려 줘요. 연동 종류는 webhook, slack, telegram, notion, gsheet이고, 이 페이지는 범용 웹훅(webhook) 이야기예요. 아래 내용은 app/src/lib/integrations.ts에서 읽은 사실만 적었어요.

이벤트

요청 헤더

헤더뜻
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)만 보내요. 원문 번호는 어떤 채널에도 보내지 않아요.