Webhook / 웹훅 등록과 이벤트

웹훅 등록과 이벤트

서명 진행을 계속 조회하지 않아도 되도록, 일이 생기면 우리가 지정한 URL 로 POST 합니다. 콘솔의 설정 › 개발자에서 URL 을 등록하고 받을 이벤트를 고르면 서명 시크릿이 한 번 표시됩니다.

이벤트

이벤트	언제
`document.sent`	요청을 만들어 서명자에게 보냈을 때
`document.viewed`	서명자가 링크를 열어 문서를 봤을 때
`document.signed`	서명자 한 명이 서명을 마쳤을 때
`document.completed`	모든 서명자가 서명해 완료본이 만들어졌을 때
`document.rejected`	서명자가 거절해 문서가 종료됐을 때
`document.canceled`	요청자가 문서를 취소했을 때
`document.expired`	기한이 지나 문서가 만료됐을 때

요청 형태

메서드는 항상 POST, 본문은 application/json
X-PinderSign-Event: 이벤트 이름
X-PinderSign-Signature: sha256=<HMAC> 형식의 본문 서명
X-PinderSign-Delivery: 전송 건 ID. 같은 값이 다시 오면 재시도입니다

관리

GET/webhooks

POST/webhooks

PATCH/webhooks/:id

DELETE/webhooks/:id

PATCH 로 구독 이벤트를 바꾸거나 active: false 로 잠시 멈출 수 있습니다. 목록 응답에는 마지막 전송 결과와 실패·대기 건수가 함께 들어 있어 웹훅이 잘 가고 있는지 바로 보입니다.

받을 이벤트 이름에 오타가 있으면 400 으로 거절합니다. 받아 두면 영영 아무것도 오지 않는 웹훅이 되기 때문입니다. 쓸 수 있는 이름은 GET /integration-options 로도 받을 수 있습니다.

이전완료본과 인증서 받기 다음서명 검증과 재시도

더 궁금한 점이 있나요?

콘솔 사용법은 사용자 가이드를 보세요. 연동 중 막히면 hello@lillo.cx 로 요청·응답을 함께 보내 주세요.

웹훅 등록

bash

curl -X POST https://api.pindersign.net/v1/webhooks \
  -H "Authorization: Bearer psk_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/pindersign",
    "events": ["document.completed", "document.rejected"]
  }'

# → secret 은 이 응답에서 한 번만 보입니다

우리가 보내는 요청

http

POST /webhooks/pindersign HTTP/1.1
Content-Type: application/json
X-PinderSign-Event: document.completed
X-PinderSign-Signature: sha256=3f1c…
X-PinderSign-Delivery: 4e4b679f…

{
  "event": "document.completed",
  "data": {
    "documentId": "8f2a…",
    "title": "2026년 프리랜서 용역계약서",
    "verificationKey": "9490bc44…",
    "completedAt": "2026-09-15T13:02:13.227Z"
  },
  "sentAt": "2026-09-15T13:02:14.001Z"
}