Webhook 검증 (Signature)

​

사전 준비

​

웹훅 - 검증 KEY 준비하기

1. 포탈 > 설정 > 결제 설정 > 웹훅 설정으로 이동합니다.
2. 검증하고자 하는 웹훅의 상세 페이지에 들어갑니다.
3. 상세 페이지에서 “검증 KEY”를 복사합니다.

​

검증 단계

​

1. Steppay-Signature 헤더 구조 이해하기

timestamp=1706002316,key=BMFfPB/HjnZeJrwA4wC1csUDzkINZsaExF99X3/Q9phE=

• timestamp: 웹훅이 발송된 시간 정보
• key: 검증을 위해 인코딩된 서명 값

​

2. timestamp와 요청 본문 결합하기

1. Steppay-Signature 헤더에서 timestamp 값을 추출합니다.
2. 추출한 timestamp 값과 웹훅 요청의 본문 데이터(requestBody)를 "timestamp.requestBody" 형식으로 결합합니다.

​

3. 결합된 문자열 암호화하기

1. 결합한 문자열을 Steppay 포탈에서 받은 검증 키와 함께 HmacSHA256 함수를 사용하여 암호화합니다.
   • 이 과정에서 결합된 문자열은 "timestamp.requestBody" 형식이어야 합니다.
   • 검증 키는 비밀 키로 사용됩니다.
2. 암호화된 결과값을 Base64 형식으로 인코딩합니다.

​

4. 헤더의 서명 값과 암호화 결과 비교하기

1. 인코딩된 결과값을 Steppay-Signature 헤더의 key 값과 비교합니다.
   • 헤더의 key 값이 여러 개일 경우 ; 로 구분되며, 모든 key 값 중 하나라도 인코딩된 값과 일치하면 검증이 성공합니다.

헤더의 key 값이 여러 개일 경우 예시

timestamp=1706002316,key=BMFfPB/HjnZeJrwA4wC1csUDzkINZsaExF99X3/Q9phE=;H3uZhieE19k/eF3ARNwjeQhdrJErf8Z8THV108mnC9w=

​

검증 코드

• Javascript
  const crypto = require("crypto");
  
  const SteppayWebhookUtil = {
    /**
     * Steppay-Signature 헤더 값과 요청 데이터, 비밀 키를 사용하여 서명을 검증합니다.
     *
     * @param {string} signature 수신받은 'Steppay-Signature' header 값
     * @param {string} payload 수신받은 request data 전문
     * @param {string} secret 포탈에서 발급받은 secret key
     * @throws {Error} 서명이 유효하지 않을 경우 에러를 발생시킵니다.
     */
    verifySignature: function (signature, payload, secret) {
      // timestamp, payload로 encodeKeys 생성
      const timestamp = signature
        .split(",", 2)
        .find((part) => part.startsWith("timestamp="))
        .split("=")[1];
      const encodeKey = this.encodeHmacSha256(
        `${timestamp}.${payload}`,
        secret
      );
  
      // header의 encodeKeys 추출
      const headerEncodeKeys = signature
        .split(",")
        .find((part) => part.startsWith("key="))
        .split("key=")[1]
        .split(";");
  
      // header의 encodeKeys와 생성한 encodeKeys 비교
      if (
        !headerEncodeKeys.some((headerEncodeKey) =>
          headerEncodeKey.includes(encodeKey)
        )
      ) {
        throw new Error("Invalid signature");
      }
    },
  
    /**
     * HmacSha256로 인코딩합니다.
     *
     * @param {string} payload
     * @param {string} secret
     * @return {string}
     */
    encodeHmacSha256: function (payload, secret) {
      const hmac = crypto.createHmac("sha256", secret);
      return hmac.update(payload).digest("base64");
    },
  };
  
  module.exports = SteppayWebhookUtil;
  
• Kotlin

  검증에 지속적으로 실패할 경우 만약 요청을 클래스로 받았을 때, 클래스를 문자열로 변환하는 방식에 따라 의도한대로 문자열 변환이 되지 않을 수 있습니다. 만약 검증 과정에서 지속적으로 문제가 생긴다면, 처음부터 데이터를 String 형태로 받는 것이 더 나을 수 있습니다.

  object SteppayWebhookUtil {
  
      /**
       * signature 검증합니다.
       *
       * @param signature 수신받은 'Steppay-Signature' header 값
       * @param payload 수신받은 request data 전문
       * @param secret 포탈에서 발급받은 secret key
       * @throws SteppaySignatureException Steppay 에서 발생하는 예외에 대한 custom exception을 재정의하는 것을 권장 드립니다.
       */
      fun verifySignature(
          signature: String,
          payload: String,
          secret: String,
      ) {
          // timestamp, payload로 encodeKeys 생성
          val timestamp = signature.split(",", limit = 2)[0].split("=")[1].toLong()
          val encodeKey = encodeHmacSha256("$timestamp.$payload", secret)
  
          // header의 encodeKeys 추출
          val headerEncodeKeys = signature.split(",")
              .map { it.split("=", limit = 2) }
              .filter { it[0] != "timestamp" }
              .map { it[1] }
  
          // header의 encodeKeys와 생성한 encodeKeys 비교
          if (headerEncodeKeys.none { headerEncodeKey -> headerEncodeKey.contains(encodeKey) }) {
              throw SteppaySignatureException("Invalid signature")
          }
      }
  
      /**
       * HmacSha256로 인코딩 합니다.
       *
       * @param payload String
       * @param secret String
       * @return String
       */
      private fun encodeHmacSha256(
          payload: String,
          secret: String,
      ): String {
          val sha256Hmac = Mac.getInstance("HmacSHA256")
          val secretKey = SecretKeySpec(secret.toByteArray(Charsets.UTF_8), "HmacSHA256")
          sha256Hmac.init(secretKey)
          return Base64.getEncoder().encodeToString(sha256Hmac.doFinal(payload.toByteArray(Charsets.UTF_8)))
      }
  }