G7 웹훅 이벤트 연동 모듈 - Glitter Connect

Glitter Connect는 그누보드7(Gnuboard7) 환경에서 외부 시스템과 이벤트를 안전하게 연결하고, Webhook 수신부터 이벤트 전달과 재처리까지 일관된 방식으로 관리할 수 있도록 설계한 확장 모듈입니다.

단순히 HTTP 요청을 주고받는 기능을 넘어, 연결 설정과 인증, 이벤트 중복 방지, 비동기 전달, 실패 기록과 재전달 기능을 하나의 구조로 통합했습니다.

특정 외부 서비스나 API 제공업체에 종속되지 않는 범용 이벤트 연동 계층을 지향하며, 기존 시스템과의 호환성을 유지하면서도 새로운 연결에는 강화된 서명 정책을 기본으로 적용하도록 설계했습니다.

주요 특징: 양방향 Webhook, HMAC-SHA256 서명, Idempotency, Outbox, 비동기 Queue, Retry / Replay, Dead Letter, 전달 이력 관리, SSRF 방어, 관리자 UI

---

1. Glitter Connect란?

Glitter Connect는 그누보드7과 외부 서비스를 연결하기 위한 이벤트 통합 계층입니다.

외부 시스템에서 발생한 이벤트를 수신하거나, 그누보드7 내부에서 발생한 이벤트를 다른 서비스로 전달할 수 있는 공통 기반을 제공합니다.

이 과정에서 연결 대상과 인증 정보를 관리하고, 이벤트를 식별·검증하며, 중복 처리와 전달 실패에 대응합니다.

주요 구성 요소는 다음과 같습니다.

구성 요소	역할
Connection	외부 시스템과의 연결 및 인증 정책 관리
Credential	연결에 사용하는 Secret 등 자격증명 관리
Endpoint	외부 Webhook 수신 주소와 인증 정책 관리
Subscription	이벤트 전달 대상 및 구독 설정
Inbound	외부 이벤트 수신·서명 검증·중복 처리
Outbox	이벤트 기록과 전달 작업 생성
Delivery	외부 대상에 이벤트 전송 및 상태 관리
Retry / Replay	실패한 전달의 자동 재시도와 수동 재전달
Dead Letter	전달할 수 없는 작업의 격리 및 관리

각 구성 요소는 독립적인 책임을 가지면서 하나의 이벤트 처리 흐름으로 연결됩니다.

이벤트 처리 흐름

Inbound — 외부 시스템에서 그누보드7로

외부 시스템
    ↓
Webhook Endpoint
    ↓
요청 시각·서명·이벤트 식별자 검증
    ↓
Idempotency 검사
    ↓
수신 기록 및 이벤트 처리

Outbound — 그누보드7에서 외부 시스템으로

이벤트 생성
    ↓
Outbox 기록
    ↓
Subscription에 따른 Delivery 생성
    ↓
Queue / Scheduler
    ↓
서명 생성 및 HTTPS 전송
    ↓
성공 기록 / Retry / Dead Letter

이러한 구조는 이벤트 생성과 외부 전송의 책임을 분리하고, 외부 서비스의 응답 지연이나 일시적인 네트워크 장애에 대응하기 위한 기반을 제공합니다.

범용성과 활용 분야

Glitter Connect의 범용성은 특정 서비스 전용 연동 코드가 아니라 공통된 이벤트 수신·전달 구조를 제공한다는 데 있습니다.

예를 들어 다음과 같은 시스템을 연결하는 기반으로 활용할 수 있습니다.

• 쇼핑몰·전자상거래: 주문, 결제, 배송 상태 변경 이벤트 연동
• 예약·접수 시스템: 예약 생성, 변경, 취소 및 상태 알림
• 알림 서비스: 이벤트에 따른 외부 알림 시스템 호출
• 업무 자동화: 외부 업무 시스템과 이벤트 기반 작업 연계
• 외부 API·SaaS: 서비스 간 상태 변경 및 데이터 동기화
• 자체 구축 서비스: 서로 다른 애플리케이션 사이의 이벤트 전달

다만 GitHub, Stripe, Slack 등 외부 서비스가 사용하는 고유한 서명 방식과 이벤트 구조를 모두 자동 지원한다는 의미는 아닙니다. Glitter Connect의 자체 프로토콜과 다른 서비스는 별도의 변환 계층이나 서비스별 어댑터가 필요할 수 있습니다.

또한 현재 배포 형태는 그누보드7 전용 확장 모듈이며, 다른 PHP 프레임워크에 직접 설치하는 독립형 패키지는 아닙니다.

---

2. 주요 기능

Webhook 수신 및 서명 검증

외부 시스템에서 전달하는 Webhook 요청을 전용 Endpoint로 수신합니다.

요청 시각, 서명, 이벤트 식별자, Idempotency-Key를 검증하며, Endpoint별 활성 상태와 요청 본문 크기 제한을 적용합니다.

HMAC-SHA256 기반 서명을 지원하며, 기존 v0과 강화된 v1 프로토콜을 구분해 처리합니다.

v1에서는 서명 검증에 실패한 요청을 자동으로 v0으로 낮춰 처리하지 않아 의도하지 않은 프로토콜 다운그레이드를 방지합니다.

Outbound Webhook 전달

수신하거나 생성한 이벤트를 Subscription에 등록된 외부 시스템으로 전달할 수 있습니다.

전달 작업은 Outbox와 Delivery 구조를 통해 관리하며, 비동기 Queue 처리와 재시도 정책을 지원합니다.

외부 시스템의 일시적인 오류로 전달이 실패한 경우에는 상태와 재시도 정책에 따라 후속 처리를 수행합니다.

Delivery 생성 시에는 해당 Subscription의 서명 버전을 함께 기록하여, 이후 설정이 변경되더라도 기존 전달 작업의 프로토콜 계약을 유지합니다.

이벤트 중복 방지

동일한 이벤트가 반복 수신되거나 전달 작업이 중복 생성되는 상황을 줄이기 위해 이벤트 식별자와 Idempotency-Key를 사용합니다.

Inbound 수신 기록과 Outbox 이벤트에는 데이터베이스의 유일성 제약을 활용해 중복 처리를 제어합니다.

v1에서는 동일한 Idempotency-Key로 서로 다른 요청 본문이 전달되는 충돌 상황을 구분하여 처리합니다.

이는 네트워크 재시도 환경에서 이벤트 처리의 일관성을 높이기 위한 기능입니다. 다만 외부 수신 시스템까지 포함한 정확히 한 번의 실행(Exactly-once execution)을 보장하는 것은 아닙니다.

외부 수신 시스템에서도 이벤트 식별자와 Idempotency-Key를 활용한 중복 처리 방어를 권장합니다.

전달 실패 관리와 재전달

Glitter Connect는 전달 작업의 상태와 시도 이력을 관리합니다.

일시적인 네트워크 오류나 재시도 가능한 HTTP 응답에는 재시도 정책을 적용하며, 복구할 수 없는 오류는 Dead Letter 상태로 분류합니다.

관리자는 전달 이력을 확인하고 지원되는 상태의 작업을 수동으로 재전달할 수 있습니다.

잘못된 이벤트 식별자 등 전송 전에 확인할 수 있는 오류는 외부 시스템으로 요청을 보내지 않고 차단하도록 설계했습니다.

관리자 인터페이스

그누보드7 관리자 환경에서 다음 기능을 제공합니다.

• Connection 관리 및 구성 확인
• Credential 및 연결별 서명 정책 관리
• Inbound Endpoint 관리
• Subscription과 서명 버전 설정
• Delivery 상태 및 시도 이력 확인
• 전달 실패와 재전달 관리

한국어와 영어 리소스를 제공하며, 그누보드7의 인증·권한 체계 및 공식 API 클라이언트와 연동합니다.

관리자 API는 인증 및 권한 검사에 연결되며, 연결 정보 조회와 변경 작업에 대한 접근을 구분합니다.

---

3. v1.1.0의 핵심: 강화된 서명 프로토콜

Glitter Connect 1.1.0은 Inbound와 Outbound 양쪽에 서명 프로토콜 v1을 도입했습니다.

v1에서는 요청 시각과 본문뿐 아니라 Idempotency-Key까지 HMAC 서명 대상에 포함합니다.

또한 프로토콜 식별 문자열을 서명 입력에 포함하여 기존 v0과 구분합니다.

v1 서명 입력 형식

glitter-connect-v1\n{timestamp}\n{Idempotency-Key}\n{raw HTTP body}

위 표기에서 \n은 실제 줄바꿈 바이트를 의미하며, {raw HTTP body}는 재직렬화하거나 변환하지 않은 HTTP 요청 본문의 원본 바이트입니다.

서명 결과는 다음 HTTP 헤더로 전달합니다.

X-Glitter-Signature: v1=<64자리 소문자 16진수 HMAC-SHA256>

v1은 요청 시각의 허용 오차, 이벤트 식별자의 유효성, Idempotency-Key 및 서명 형식을 검증합니다.

특히 서명 검증에 실패했을 때 기존 v0으로 자동 전환하지 않으므로, 프로토콜 다운그레이드로 인증 정책이 약화되는 상황을 방지합니다.

기존 v0과 신규 v1의 호환성

기존 v0 프로토콜은 호환성을 위해 유지합니다.

새로 생성하는 Endpoint와 Subscription에는 v1을 기본으로 적용하며, 기존 설정과 전달 작업은 v0 계약을 유지합니다.

구분	기존 데이터	신규 생성
Endpoint signature_version	v0	v1
Subscription outbound_signature_version	v0	v1
Connection signature_required	false	true
Delivery 서명 버전	기존 v0 유지	Subscription의 버전 사용

기존 Connection의 signature_required=false는 이전 버전의 선택적 서명 정책을 보존하기 위한 기본값입니다. 신규 Connection은 서명 필수 정책을 기본으로 사용합니다.

Delivery 서명 버전 고정

Delivery 생성 시 Subscription의 서명 버전을 기록하므로, 이후 Subscription 설정이 변경되더라도 기존 Delivery의 재시도와 재전달에는 최초의 서명 버전이 유지됩니다.

이는 전달 작업이 생성된 시점의 인증 계약을 보존하고, 설정 변경으로 과거 전달 작업의 동작이 예기치 않게 달라지는 것을 방지하기 위한 설계입니다.

v1.1.0 주요 변경 사항 요약

• Inbound HMAC-SHA256 서명 프로토콜 v1 지원
• Outbound HMAC-SHA256 서명 프로토콜 v1 지원
• 신규 Endpoint와 Subscription의 v1 기본 적용
• 신규 Connection의 서명 필수 정책 적용
• 기존 v0 설정 및 데이터 호환성 유지
• Delivery별 Outbound 서명 버전 저장
• v1 이벤트 식별자 및 Idempotency 검증 강화
• 유효하지 않은 Outbound v1 이벤트의 전송 차단
• 관련 관리자 설정 및 다국어 리소스 반영
• 단계별 데이터베이스 마이그레이션 제공

---

4. 연결 보안과 전송 보호

Glitter Connect는 외부 시스템과 통신하는 모듈의 특성을 고려해 여러 보호 장치를 제공합니다.

서명 정책

신규 Connection은 서명 필수 정책을 기본으로 사용합니다.

Secret이 필요한 연결에서 인증 정보가 누락되면 서명 없는 요청을 대신 전송하지 않고 전달을 차단합니다.

Inbound v1은 요청 시각, 이벤트 식별자, Idempotency-Key와 본문을 검증하며, 유효하지 않은 요청을 거부합니다.

Outbound v1도 서명 생성 전에 이벤트 식별자의 유효성을 확인합니다.

외부 요청 보호

Outbound 전송에는 HTTPS를 요구하며, 내부망 및 예약된 IP 주소를 대상으로 하는 요청을 제한합니다.

DNS 확인과 목적지 IP 고정, 리다이렉트 차단, 요청 시간 제한, 응답 본문 크기 제한 등을 적용해 SSRF(Server-Side Request Forgery) 위험을 줄이도록 설계했습니다.

주요 보호 정책은 다음과 같습니다.

• HTTPS 기반 Outbound 전송
• 사설·예약된 IP 주소 차단
• DNS A/AAAA 조회 및 공인 IPv4 목적지 고정
• HTTP 리다이렉트 차단
• 비정상적인 호스트명 및 IP 표현 제한
• 전송 시간 제한
• 응답 본문 크기 제한

이러한 정책은 위험을 줄이기 위한 방어 계층이며, 모든 네트워크 공격 가능성을 제거한다는 의미는 아닙니다.

권한 분리

관리자 API는 그누보드7의 Sanctum 인증과 관리자 권한 검사에 연결됩니다.

연결 정보 조회와 변경 작업에도 별도의 권한 정책을 적용합니다.

이를 통해 일반적인 이벤트 처리 경로와 관리자 설정 경로의 책임을 구분합니다.

민감정보 관리

Secret은 암호화된 자격증명 저장 구조를 사용합니다.

다만 Secret 생성·교체 과정에서 관리자에게 제공되는 평문 값과 브라우저 요청·응답 기록은 민감정보로 관리해야 합니다.

특히 관리자 브라우저의 개발자 도구(DevTools), 네트워크 기록, 디버깅 자료를 외부에 공유할 때 Secret이 포함되지 않도록 주의해야 합니다.

운영 환경에서는 HTTPS, 관리자 접근 권한, Laravel 암호화 키와 Secret의 보관 정책을 함께 관리하는 것을 권장합니다.

---

5. 기존 환경과의 호환성

1.1.0은 기존 Glitter Connect 1.0.0의 데이터를 유지하면서 기능을 확장하는 방향으로 구성했습니다.

기존 Connection의 선택적 서명 정책, 기존 Endpoint의 v0 서명 버전, 기존 Subscription 및 Delivery의 v0 서명 계약을 유지하도록 마이그레이션 기본값을 설계했습니다.

신규 설정에는 v1을 기본으로 적용해 기존 연결을 갑자기 변경하지 않으면서 새로운 연동부터 강화된 인증 정책을 사용할 수 있습니다.

기존 데이터를 삭제하고 재설치하는 방식이 아니라, 모듈 업데이트와 단계별 마이그레이션을 통해 전환하도록 구성했습니다.

1.0.0에서 1.1.0으로 업데이트

1.1.0에는 다음 데이터베이스 변경 사항이 포함됩니다.

마이그레이션	변경 사항	기존 데이터 기본값
000002	Endpoint 서명 버전 추가	v0
000003	Receipt 본문 SHA-256 컬럼 추가	NULL
000004	Connection 서명 필수 여부 추가	false
000005	Subscription·Delivery Outbound 서명 버전 추가	v0

기존 연결의 동작을 보존하면서 신규 연결에 강화된 서명 정책을 적용하도록 구성한 변경 사항입니다.

다만 실제 운영 환경의 확장 모듈, 사용자 정의 레이아웃, 데이터베이스 상태에 따라 업데이트 결과가 달라질 수 있으므로 업데이트 전 호환성과 변경 범위를 확인해야 합니다.

특히 MariaDB의 DDL은 단계별로 커밋될 수 있으므로, 마이그레이션 중 오류가 발생했다고 해서 모든 스키마 변경이 자동으로 취소되는 것은 아닙니다.

기존 데이터를 삭제하는 방식의 강제 초기화나 무조건적인 마이그레이션 롤백은 운영 복구 방법으로 권장하지 않습니다.

---

6. 개발 및 배포 정보

항목	내용
모듈명	Glitter Connect
한글 명칭	G7 웹훅 이벤트 연동
모듈 ID	glitter-connect
공개 버전	1.1.0
개발·배포	Glitter.kr
대상 플랫폼	Gnuboard7
PHP 네임스페이스	Glitter\Connect
JavaScript 전역 객체	GlitterConnect
라이선스	MIT
배포 형태	공개 확장 모듈
소스 저장소	https://github.com/glitter-node/glitter-connect

Glitter Connect는 그누보드7의 확장 모듈 구조에 맞춰 개발했으며, Connection, Endpoint, Subscription, 이벤트 처리 서비스와 관리자 UI를 모듈 내부에서 관리합니다.

기술 스택

PHP 8.3, Laravel 12, Gnuboard7, MariaDB 10.11, JavaScript, Vite, REST API, Laravel Sanctum, Queue, Scheduler, Webhook, HMAC-SHA256, HTTPS, Inbound/Outbound, Idempotency, Retry/Replay

설계 방향

Glitter Connect는 다음 원칙을 지향합니다.

• 범용성: 특정 외부 서비스에 종속되지 않는 이벤트 연동 구조
• 호환성: 기존 연결 계약과 신규 보안 정책의 공존
• 신뢰성: Outbox, 중복 방지, 전달 이력 및 재시도
• 보안성: 서명 검증, 인증 정책, HTTPS 및 SSRF 방어
• 운영성: 관리자 설정, 상태 추적 및 수동 재전달
• 확장성: 다양한 서비스별 연동 계층을 구성할 수 있는 공통 기반

모든 외부 서비스를 별도 설정 없이 자동 연동하는 제품이 아니라, 그누보드7에서 이벤트 기반 시스템 연동을 구현하기 위한 공통 인프라라는 점이 핵심입니다.

---

7. 운영 시 참고사항

Webhook은 외부 시스템과 실제 데이터를 주고받는 기능이므로, 운영 환경에 적용하기 전에 연결 대상의 서명 프로토콜, Secret, 네트워크 접근 정책, Queue Worker 및 Scheduler 설정을 확인해야 합니다.

설치 및 업데이트 전 확인

• 그누보드7 및 PHP 실행 환경과의 호환성
• 데이터베이스 연결과 마이그레이션 적용 가능 여부
• 관리자 인증·권한 설정
• Queue Worker 및 Scheduler 동작 상태
• HTTPS와 외부 목적지 접근 정책
• Secret 및 Laravel 암호화 키 보관
• 기존 모듈 데이터와 사용자 정의 레이아웃 보존
• 운영 데이터베이스와 파일의 백업·복구 절차

데이터베이스 마이그레이션을 포함하는 업데이트에서는 기존 데이터의 백업과 복구 절차를 준비하는 것을 권장합니다.

외부 서비스 연동 시 확인

Glitter Connect의 v1 서명은 자체 프로토콜이므로, 연동 상대 시스템에서도 해당 서명 입력 형식과 헤더를 지원해야 합니다.

외부 서비스가 다른 웹훅 규격을 사용하는 경우에는 서비스별 어댑터 또는 변환 계층이 필요할 수 있습니다.

또한 비동기 전달 구조에서는 외부 시스템의 네트워크 상태나 응답 결과에 따라 재시도가 발생할 수 있으므로, 수신 시스템에서도 Idempotency-Key를 활용한 중복 처리 방어를 권장합니다.

전달 작업 운영

Queue Worker와 Scheduler가 실행되지 않으면 Delivery가 정상적으로 생성되더라도 실제 전송이 지연될 수 있습니다.

운영 환경에서는 전달 대기, 재시도, Dead Letter 상태를 정기적으로 확인하고, 외부 시스템의 장애나 인증 정보 변경에 대응할 수 있도록 관리해야 합니다.

실제 전송을 시작하기 전에는 연동 대상의 수신 정책과 테스트 가능 범위를 확인하는 것이 좋습니다.

---

8. 앞으로의 방향

Glitter Connect는 특정 외부 서비스 하나에 종속되는 연동 기능이 아니라, 다양한 서비스와 이벤트를 연결하기 위한 공통 기반을 목표로 합니다.

앞으로도 그누보드7의 확장 구조와 호환성을 유지하면서 연결 관리, 이벤트 전달의 신뢰성, 보안 정책, 운영 편의성을 지속적으로 개선할 계획입니다.

특히 다양한 외부 서비스의 웹훅 규격을 연결할 수 있는 확장 방식, 이벤트 처리 가시성, 전달 실패 분석과 운영 자동화는 향후 발전시킬 수 있는 영역입니다. 이는 향후 개선 방향이며, 현재 버전에서 모든 서비스별 어댑터를 제공한다는 의미는 아닙니다.

Glitter Connect 1.1.0은 그누보드7에서 외부 시스템과 이벤트를 안전하고 일관된 방식으로 연결하고 관리하기 위한 공개 확장 모듈입니다.

복잡한 연동 코드를 각각의 기능에 반복해서 작성하는 대신, 공통된 인증·수신·전달·재처리 구조를 활용할 수 있도록 하는 것이 이 모듈의 핵심 목적입니다.

Glitter.kr — Glitter Connect 1.1.0

---

관리자 페이지에서 설치

Glitter Connect는 그누보드7 관리자 페이지의 모듈 관리 기능을 통해 설치할 수 있습니다.

1. GitHub 저장소에서 설치 (권장)

관리자 → 모듈 관리 → 수동 설치 → GitHub

아래 저장소 URL을 입력합니다.

https://github.com/glitter-node/glitter-connect

관리자 화면의 설치 절차에 따라 저장소를 선택하고 모듈을 설치합니다.

GitHub 저장소 설치는 공개 소스와 버전 이력을 기준으로 모듈을 관리하려는 환경에 적합합니다.

운영 환경에서는 설치·업데이트 전에 데이터베이스와 파일을 백업하고, 기존 모듈 및 그누보드7 버전과의 호환성을 확인하는 것이 좋습니다.

2. ZIP 패키지 설치

GitHub Release에서 G7 모듈 설치용 ZIP을 다운로드합니다.

glitter-connect-v1.1.0.zip 다운로드

G7 관리자에서:

관리자 → 모듈 관리 → 수동 설치 → 파일 업로드

방식으로 ZIP 파일을 설치할 수 있습니다.

ZIP 설치는 특정 버전을 보관하거나, GitHub 저장소에 직접 접근하기 어려운 환경에서 수동으로 배포할 때 유용합니다.

다운로드 링크는 해당 버전의 Release 자산이 실제로 게시된 경우에 사용할 수 있습니다. 파일이 제공되지 않으면 GitHub 저장소의 Releases 페이지에서 게시된 자산을 확인하세요.

설치 후 확인

설치가 완료되면 다음 사항을 확인합니다.

1. 모듈 관리 화면에서 Glitter Connect가 정상적으로 등록되고 활성화됐는지 확인합니다.
2. 필요한 데이터베이스 마이그레이션이 적용됐는지 확인합니다.
3. 관리자 화면에서 Connection, Endpoint, Subscription 관리 기능에 접근할 수 있는지 확인합니다.
4. Queue Worker와 Scheduler가 운영 환경에서 실행되는지 확인합니다.
5. 실제 외부 시스템과 연결하기 전에 Secret과 서명 프로토콜을 설정합니다.
6. 허용된 테스트 환경에서 Webhook 수신 및 전달 흐름을 확인합니다.

---

라이선스

MIT License

Copyright (c) 2026 Glitter.kr

Glitter Connect는 MIT 라이선스로 공개 배포합니다.

MIT 라이선스는 저작권 고지와 라이선스 조건을 준수하는 범위에서 사용, 수정, 재배포 및 상업적 활용을 허용하는 오픈소스 라이선스입니다.

정확한 저작권 고지와 라이선스 조건은 저장소의 LICENSE 파일을 따릅니다.

---

권장 설치 방식

이 버전은 ZIP 설치보다 GitHub 저장소 설치를 권장합니다.

G7 관리자에서 GitHub 저장소 URL을 이용하면 모듈의 소스와 버전 이력을 기준으로 설치 및 업데이트 흐름을 관리하기 쉽습니다.

https://github.com/glitter-node/glitter-connect

특정 릴리스 파일을 별도로 보관하거나 폐쇄망·수동 배포 환경에서 설치해야 한다면 GitHub Release에 등록된 ZIP 패키지를 활용할 수 있습니다.

공개 저장소: https://github.com/glitter-node/glitter-connect

릴리스: https://github.com/glitter-node/glitter-connect/releases/tag/v1.1.0