가이드

웹훅 연동 가이드

이 문서는 그로블 웹훅을 연결하는 분들을 위한 가이드예요.
각 이벤트 응답의 모든 필드 정의가 필요하시다면 웹훅 이벤트 페이지를 확인해 주세요.

1. 웹훅이 무엇인가요?

매번 새로운 소식이 있는지 확인할 필요 없어요. 그로블이 먼저 소식을 보내드리는 ‘자동 알림’ 기능이에요.
결제 완료, 환불, 구독 해지 같은 중요한 일이 생기면,
판매자님이 등록해둔 URL로 그로블이 즉시 상세 내용을 담아 안내(HTTPS POST 요청)를 보내드려요.

지원하는 이벤트

  • payment.completed — 일반결제 완료

  • subscription_payment.completed — 정기결제 완료

  • payment.cancel_requested — 일반결제 취소 요청

  • subscription.cancel_requested — 정기결제 해지 신청

2. 5분 안에 첫 웹훅 받기

1단계. 그로블에 엔드포인트를 등록해 주세요

내 스토어 - 설정 페이지에서 HTTPS 엔드포인트를 기입하고, 구독할 이벤트를 선택해 저장해요.

webhook.png
* HTTPS 엔드포인트와 구독할 이벤트를 선택해주세요

첫 등록을 성공하면 시크릿 키가 발급돼요. 딱 한 번만 볼 수 있으니까
바로 복사해서 안전한 곳에 저장해 주세요!

webhook2.png
* 첫 등록으로 발급된 웹훅 시크릿 키를 안전한 곳에 저장해 주세요

만약 시크릿 키를 분실했다면, 재발급할 수 있어요.

image.png
* 재발급한 시크릿 키와 이전 시크릿 키는 24시간 동안 모두 사용할 수 있어요.

시크릿 키 재발급은 24시간마다 가능해요.

2단계. 첫 이벤트 받기

실제 결제를 일으키거나 관리 페이지의 테스트 발송 기능으로 웹훅 작동을 확인해요.

webhook3.png
* 테스트 성공 여부를 확인할 수 있어요

3단계. 서명 검증과 멱등 처리 추가

서명 검증을 추가하세요. 서명 검증이 없으면 누구나 “결제 완료” payload를 위조해서 보낼 수 있어요.

3. 요청 형식

요청 헤더

헤더

설명

Content-Type

항상 application/json

X-Groble-Signature

현재 시크릿 키로 만든 HMAC-SHA256 서명

X-Groble-Timestamp

서명 계산에 사용한 Unix timestamp(초)

X-Groble-Idempotency-Key

이번 전송의 고유 키

X-Groble-Signature-Previous

시크릿 키 교체 후 24시간 동안만 전달되는 이전 시크릿 기준 서명

요청 본문

모든 웹훅은 아래 구조로 전달됩니다.

{
     "id": "evt_xxxxxxxxxxxxxxxxxxxxxxxx",
     "type": "payment.completed",
     "version": "2026-04-21",
     "occurredAt": "2026-04-22T10:00:00+09:00",
     "data": {
        "object": {}
    }
}

  • id: 전송 고유 식별자

  • type: 이벤트 타입

  • version: payload 스키마 버전

  • occurredAt: 실제 이벤트 발생 시각

  • data.object: 이벤트별 상세 데이터

이벤트별 상세 필드는 웹훅 이벤트 페이지에서 확인해 주세요.

4. 서명 검증

서명 검증은 아래 방식으로 수행해요.

signature = HEX(HMAC-SHA256(secret, "{timestamp}.{raw_body}"))

필수 규칙은 아래 4가지예요.

  • JSON 파싱 전의 원본 body bytes로 계산해야 해요.

  • X-Groble-Signature와 X-Groble-Timestamp를 반드시 확인해야 합니다.

  • 시크릿 키 교체 중에는 X-Groble-Signature-Previous도 함께 허용해야 합니다.

  • timestamp는 현재 시각 기준 ±5분 이내인지 확인해야 합니다.

검증 순서는 아래처럼 구현하면 돼요.

1. signature, signature_previous, timestamp 헤더를 읽습니다
2. raw body를 원본 bytes 그대로 읽습니다
3. "{timestamp}.{raw_body}"로 message를 만듭니다
4. secret으로 HMAC-SHA256을 계산합니다
5. 계산 결과가 signature 또는 signature_previous와 일치하는지 확인합니다
6. timestamp가 5분 이내인지 확인합니다
7. 통과한 경우에만 payload를 파싱합니다

5. 처리 규칙

수신 서버는 아래 원칙으로 처리해 주세요.

  • 서명 검증을 먼저 수행해 주세요.

  • 가능한 한 빨리 2xx를 반환해 주세요.

  • 응답은 10초 안에 끝내는 것을 기준으로 구현해 주세요.

  • X-Groble-Idempotency-Key로 중복 전송을 막아 주세요.

  • 이벤트 도착 순서는 보장되지 않으므로 occurredAt 기준으로 판단해 주세요.

  • 리다이렉트는 따라가지 않으므로 3xx 응답을 사용은 불가해요.

상태 코드별 기본 동작은 아래와 같습니다.

  • 2xx: 성공

  • 408, 429, 5xx: 재시도

  • 400, 401, 403, 404: 최종 실패

  • 410: 엔드포인트 비활성화

6. 최소 체크리스트

  • HTTPS URL 등록

  • 시크릿 키를 안전하게 저장

  • 원본 body 기준으로 서명 검증

  • timestamp ±5분 검증

  • X-Groble-Idempotency-Key 멱등 처리

  • 10초 안에 2XX 응답 반환