웹훅 개발가이드

{
  "eventType": "CONTROL_START",
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": 1723600000000,
  "data": [ "TESTCASE003S1", "TESTCASE005S1" ]
}

# eventId: 발송 건 고유 ID · data: 영향 API 목록

# 1) 헤더에서 서명 추출
received = header["X-Webhook-Signature"]   # "sha256=...."

# 2) 본문 원문으로 HMAC-SHA256 재계산
digest   = HMAC_SHA256(secret, rawBody)     # bytes
expected = "sha256=" + toHexLower(digest)

# 3) 상수 시간 비교
valid    = constantTimeEquals(received, expected)

const crypto = require('crypto');

// rawBody: express.raw() 등으로 확보한 원문 Buffer
function verify(rawBody, header, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(rawBody)
          .digest('hex');
  const a = Buffer.from(header);
  const b = Buffer.from(expected);
  return a.length === b.length &&
         crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

# raw_body: request.get_data() 로 확보한 bytes
def verify(raw_body, header, secret):
    digest = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    expected = 'sha256=' + digest
    return hmac.compare_digest(expected, header)

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;

// rawBody: 파싱 전 원문 문자열
boolean verify(String rawBody, String header, String secret) throws Exception {
  Mac mac = Mac.getInstance("HmacSHA256");
  mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
  byte[] hash = mac.doFinal(rawBody.getBytes(StandardCharsets.UTF_8));
  StringBuilder hex = new StringBuilder();
  for (byte b : hash) hex.append(String.format("%02x", b));
  String expected = "sha256=" + hex;
  return MessageDigest.isEqual(
      expected.getBytes(StandardCharsets.UTF_8),
      header.getBytes(StandardCharsets.UTF_8));
}

# 정상 접수
HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": "OK",
  "eventType": "CONTROL_START"
}

# 서명 검증 실패
HTTP/1.1 401 Unauthorized
{
  "result": "ERROR",
  "message": "서명 검증에 실패하였습니다."
}

# 필수 헤더 누락
HTTP/1.1 400 Bad Request
{
  "result": "ERROR",
  "message": "필수 헤더가 누락되었습니다."
}