이벤트 페이로드 명세

개요

DataGSM Event가 외부 서버로 전송하는 이벤트 페이로드의 공통 구조입니다. 모든 페이로드는 application/json Content-Type으로 HTTP POST 요청 본문에 담겨 전송되며, 봉투(envelope) 구조와 data 형식은 세 도메인(student / club / project)이 모두 동일합니다. 도메인별로 다른 것은 object 안에 담기는 필드뿐입니다.

각 도메인의 object 필드와 예시는 아래 상세 페이지에서 확인할 수 있습니다.

학생 — student.updated
동아리 — club.updated
프로젝트 — project.updated

공통 봉투 구조

모든 이벤트 페이로드는 다음 공통 구조를 따릅니다.

{
  "id": "evt_3f9a2c1b8e0d4a7f9c2e1b6d5a4f3c2e",
  "event": "student.updated",
  "timestamp": "2026-06-23T05:21:48.123Z",
  "data": {
    "old": [],
    "new": []
  }
}

필드	타입	설명	예시
`id`	`string`	이벤트 고유 ID. `evt_` + UUID(하이픈 제거). 멱등성 키로 사용 권장	`evt_3f9a...3c2e`
`event`	`string`	이벤트 타입 (EventType 목록 참고)	`student.updated`
`timestamp`	`string`	이벤트 발생 시각 (`ISO-8601`, UTC)	`2026-06-23T05:21:48.123Z`
`data`	`object`	변경 내용. `old` / `new` 두 리스트	(아래 참고)

EventType 목록

이벤트 이름	설명	상세 명세
`student.updated`	학생 정보 변경 (수정·졸업·자퇴·역할 변경 포함)	학생
`club.updated`	동아리 생성·수정·삭제	동아리
`project.updated`	프로젝트 생성·수정·삭제	프로젝트

`data` 구조 — `old` / `new`

data는 변경 전(old) 과 변경 후(new) 두 개의 리스트이며, 각 항목은 { index, object } 형태입니다.

{
  "data": {
    "old": [
      { "index": 0, "object": { "...": "변경 전 전체 정보" } }
    ],
    "new": [
      { "index": 0, "object": { "...": "변경 후 전체 정보" } }
    ]
  }
}

필드	타입	설명
`index`	`integer`	`old`↔`new` 매칭 순번. 같은 `index`는 같은 변경 건을 가리킴
`object`	`object`	해당 시점의 전체 정보. 생성·삭제 시에는 빈 객체 `{}`

한 번의 작업으로 여러 대상이 동시에 변경될 수 있습니다 (예: 3학년 일괄 졸업). 이때 old/new는 여러 항목을 가집니다.
단일 변경도 항상 길이 1 리스트로 전송됩니다. 구조가 항상 동일하므로 분기 처리가 필요 없습니다.
index는 단순 짝 매칭용 순번입니다. 실제 식별은 object 안의 식별자 필드(student_id, club_id, project_id)를 사용하세요.
old와 new는 항상 같은 길이이며, 각 object는 변경된 필드만이 아니라 전체 정보를 담습니다.

생성 · 수정 · 삭제 판별

같은 index의 old.object / new.object 중 어느 쪽이 빈 객체 {}인지로 종류를 구분합니다.

종류	`old[i].object`	`new[i].object`
수정	변경 전 전체 정보	변경 후 전체 정보
생성	`{}` (빈 객체)	생성된 전체 정보
삭제	삭제 전 전체 정보	`{}` (빈 객체)

학생 도메인(student.updated)은 현재 수정만 발행합니다 (졸업·자퇴도 row가 남으므로 삭제가 아닌 role 변화로 표현). 생성/삭제 표현은 club/project 및 향후 확장을 위해 구조상 지원됩니다.

페이로드 수신 시 유의사항

페이로드 본문 외에 X-DataGSM-Signature 헤더가 함께 전달됩니다. 위조 요청을 식별하기 위해 반드시 서명을 검증하세요.
data.old / data.new를 index로 짝지어 object의 변경 전/후를 비교하세요. 실제 대상 매칭은 object 내 식별자(student_id 등)로 합니다.
단건도 항상 리스트로 처리하고, 빈 object {}(생성/삭제)를 안전하게 처리하세요.
DataGSM 서버는 응답 본문을 사용하지 않습니다. 수신 서버는 가능한 한 빠르게 2xx 응답을 반환하고, 실제 처리는 별도 큐·잡으로 분리하는 것을 권장합니다.
응답이 2xx가 아니거나 타임아웃이 발생하면 지수 백오프(1s → 10s → 100s)로 최대 3회 재시도되며, 그 이후에는 영구 손실됩니다.
동일 이벤트가 재시도로 인해 중복 수신될 수 있으므로, id를 멱등성 키로 저장해 중복 수신을 무시하도록 구현하세요.