웹훅 엔드포인트를 등록하면 응답에 webhookSecret이라는 값이 포함됩니다. 이게 도대체 뭐고, 왜 필요할까요? 이 글에서 쉽게 설명드립니다.

한 줄 요약

webhookSecret은 "이 요청이 진짜 택배API에서 보낸 것인지" 확인하는 비밀 열쇠입니다.

왜 필요한가요?

웹훅은 외부에서 여러분의 서버로 POST 요청을 보내는 방식입니다. 문제는 누구든지 여러분의 웹훅 URL을 알면 가짜 요청을 보낼 수 있다는 것입니다.

비유로 이해하기

아파트 경비실을 생각해보세요. 택배 기사가 왔다고 하면 경비원이 그냥 문을 열어줄까요? 아닙니다. 택배사 유니폼, 차량, 송장을 확인합니다.

webhookSecret은 이 "확인 과정"에 쓰이는 비밀 암호입니다. 택배API가 보내는 모든 웹훅에는 이 암호로 만든 서명(signature)이 포함되어 있고, 여러분의 서버는 이 서명을 검증해서 진짜 택배API에서 보낸 것인지 확인합니다.

서명 검증은 어떻게 동작하나요?

택배API가
배송 상태 변경 감지
→
webhookSecret으로
서명(HMAC) 생성
→
서명을 헤더에 넣어
여러분 서버로 POST
→
여러분 서버가
서명 일치 여부 확인
  1. 택배API가 배송 상태 변경을 감지하면, webhookSecret과 요청 본문(payload)으로 HMAC-SHA256 서명을 생성합니다.
  2. 이 서명을 X-Webhook-Signature 헤더에 넣어 여러분의 서버로 전송합니다.
  3. 여러분의 서버는 같은 webhookSecret으로 서명을 다시 계산해서, 헤더의 서명과 일치하는지 비교합니다.
  4. 일치하면 진짜 택배API의 요청 → 처리. 불일치하면 가짜 요청 → 거부.

webhookSecret은 언제 받나요?

웹훅 엔드포인트를 생성할 때 응답에 포함됩니다:

// 엔드포인트 생성 응답
{
  "isSuccess": true,
  "data": {
    "endpointId": "ep_20260313_...",
    "url": "https://example.com/webhooks/delivery",
    "webhookSecret": "whsec_0123456789abcdef..."  // 이 값!
  }
}
반드시 안전하게 보관하세요

webhookSecret은 생성 시 단 1회만 평문으로 반환됩니다. 이후에는 조회할 수 없습니다.

환경변수나 시크릿 매니저에 저장하세요. 분실 시 시크릿 재발급 API로 새로 발급받을 수 있습니다.

서명 검증 구현 (Node.js 예제)

const crypto = require('crypto');

function verifyWebhook(rawBody, headers, webhookSecret) {
  const signature = headers['x-webhook-signature'];
  const timestamp = headers['x-webhook-timestamp'];

  // 같은 방식으로 서명을 다시 계산 (payload는 반드시 원본 바이트)
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // 헤더값: sha256={hex} → timing-safe 비교
  const expectedBuf = Buffer.from(`sha256=${expected}`);
  const receivedBuf = Buffer.from(signature || '');
  return (
    expectedBuf.length === receivedBuf.length &&
    crypto.timingSafeEqual(expectedBuf, receivedBuf)
  );
}

// Express.js 예시 — 서명 검증에는 원본 바이트가 필요하므로
// 이 라우트에는 express.json() 대신 express.raw()를 적용합니다.
app.post('/webhooks/delivery', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  if (!verifyWebhook(rawBody, req.headers, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: '서명 검증 실패' });
  }

  // 서명 검증 통과 - 안전하게 처리
  const { items } = JSON.parse(rawBody);
  for (const item of items) {
    console.log(`배송 상태 변경: ${item.trackingNumber} → ${item.currentStatus}`);
  }
  res.json({ ok: true });
});

검증을 안 하면 어떻게 되나요?

서명 검증 없이 웹훅을 처리하면 다음과 같은 공격에 노출될 수 있습니다:

서명 검증은 선택이 아닌 필수

프로덕션 환경에서는 반드시 서명을 검증하세요. 택배API는 모든 웹훅에 HMAC-SHA256 서명을 포함하므로, 몇 줄의 코드만 추가하면 안전하게 보호할 수 있습니다.

webhookSecret 관련 API

작업 API 설명
발급 엔드포인트 생성 생성 시 자동 발급 (직접 지정도 가능)
재발급 시크릿 재발급 분실 시 새 시크릿 발급 (기존 값 폐기)
검증 웹훅 페이로드 수신 시 서명 검증 방법
엔드포인트 생성 API 문서 → 웹훅 가이드 보기 ← 블로그 목록