웹훅

웹훅을 사용하면 애플리케이션이 PDFSimple로부터 실시간 이벤트 알림을 받을 수 있습니다. API로 작업 상태를 폴링하는 대신, 엔드포인트를 등록하면 이벤트가 발생했을 때 PDFSimple이 서명된 페이로드를 POST 방식으로 전송합니다.

웹훅 설정하기

1. 대시보드 → 웹훅으로 이동하여 엔드포인트 추가를 클릭하세요.
2. HTTPS 엔드포인트 URL을 입력하세요(예: https://yourapp.com/webhooks/pdfsimple).
3. 수신하려는 이벤트를 선택하세요(예: job.completed, job.failed).
4. 생성을 클릭하세요. 고유한 웹훅 비밀키가 표시됩니다 — 즉시 복사하세요, 한 번만 표시됩니다.
5. 애플리케이션의 환경 변수에 비밀키를 안전하게 저장하세요.

웹훅 이벤트

• job.completed — PDF 처리 작업이 성공적으로 완료되었습니다. 페이로드에는 작업 ID, 출력 파일 URL, 메타데이터가 포함됩니다.
• job.failed — 작업 중 오류가 발생했습니다. 페이로드에는 오류 메시지가 포함됩니다.

웹훅 서명 검증하기

모든 웹훅 요청에는 웹훅 비밀키를 사용해 계산된 원시 요청 본문의 HMAC-SHA256 서명을 담은 X-PDFSimple-Signature 헤더가 포함됩니다. 페이로드를 처리하기 전에 항상 이 서명을 검증하세요.

const crypto = require('crypto');

function verifySignature(rawBody, secret, signature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

재시도 및 전달 보장

엔드포인트가 30초 이내에 2xx 응답을 반환하지 않으면 PDFSimple은 지수 백오프 방식으로 최대 30일간 5회까지 전달을 재시도합니다. 웹훅 이벤트는 30일간 보관됩니다.