webhookSecret이란? 웹훅 서명 검증 쉽게 이해하기

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

한 줄 요약

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

왜 필요한가요?

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

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

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..."  // 이 값!
  }
}

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

const crypto = require('crypto');

function verifyWebhook(req, webhookSecret) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);

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

  // 헤더값: sha256={hex} → 비교
  return signature === `sha256=${expected}`;
}

// Express.js 예시
app.post('/webhooks/delivery', (req, res) => {
  if (!verifyWebhook(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: '서명 검증 실패' });
  }

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

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

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

• 가짜 배송 완료 알림: 공격자가 "배송 완료" 가짜 요청을 보내 주문 상태를 조작
• 봇 공격: 대량의 가짜 웹훅 요청으로 서버 리소스 낭비
• 데이터 변조: 실제와 다른 배송 정보를 주입하여 고객에게 잘못된 알림 전송

webhookSecret 관련 API