Webhook 페이로드 참고 자료

이런 경우에 해당합니다

Timemark webhook을 수신하는 엔드포인트를 작성하면서 이를 파싱할 수 있도록 요청 본문의 정확한 구조를 알아야 하는 경우입니다.

전송 방식

각 전송은 JSON 본문을 담은 HTTP POST입니다. 본문에는 이벤트와 관련된 사진 정보가 포함됩니다. 엔드포인트는 제한 시간 내에 2xx 응답을 반환해야 하며, 그 외의 경우는 전송 실패로 간주되어 재시도됩니다.

페이로드 예시

다음은 새 사진 이벤트(event_type: "photo.uploaded")에 대해 전송되는 본문입니다:

{
  "event_type": "photo.uploaded",
  "event_id": "3f4566da-938d-4e11-834b-ba9e3faec98c",
  "group_name": "Group Scenery",
  "project_name": "Project Sunrise",
  "photo_code": "A1BCDEFGHIJ23K",
  "photo_name": "2025-12-11 13.45.00_1388 Central Park, New York, example.jpg",
  "photo_url": "https://example.com/uploads/photos/123456.jpg",
  "thumbnail_url": "https://example.com/uploads/photos/123456.jpg",
  "photo_timestamp": "2025-12-11T13:45:00Z",
  "photo_location": {
    "location_name": "Central Park, New York, USA",
    "location_latitude": "40.785091",
    "location_longitude": "-73.968285"
  },
  "member": {
    "member_name": "Alice Chen",
    "member_short_name": "Alice",
    "member_profile_picture_url": "https://example.com/user/profile_photo/123456.jpg",
    "member_contact": "alice.chen@example.com"
  },
  "device_model": "Apple iPhone 14 Pro Max",
  "custom_notes": [
    {
      "title": "custom_note_title_1",
      "content": "custom_note_content_1"
    },
    {
      "title": "custom_note_title_2",
      "content": "custom_note_content_2"
    }
  ]
}

필드 참고

필드	유형	설명
event_type	string	실행된 이벤트입니다. 새 사진 이벤트의 경우 photo.uploaded입니다.
event_id	string	이 전송의 고유 ID입니다. 재시도된 전송을 중복 제거하는 데 사용하세요.
group_name	string	사진이 속한 팀입니다.
project_name	string	사진이 속한 프로젝트입니다.
photo_code	string	사진의 검증 코드로, Photo Verification Center에서도 사용됩니다.
photo_name	string	촬영 시간과 위치를 포함한 사진의 파일 이름입니다.
photo_url	string	원본 크기 이미지의 URL입니다.
thumbnail_url	string	썸네일 이미지의 URL입니다.
photo_timestamp	string	ISO 8601(UTC) 형식의 촬영 시간입니다.
photo_location	object	촬영 위치입니다. 아래를 참고하세요.
photo_location.location_name	string	사람이 읽을 수 있는 장소 이름 또는 주소입니다.
photo_location.location_latitude	string	위도이며 문자열입니다.
photo_location.location_longitude	string	경도이며 문자열입니다.
member	object	사진을 촬영한 멤버입니다. 아래를 참고하세요.
member.member_name	string	전체 표시 이름입니다.
member.member_short_name	string	짧은 이름입니다.
member.member_profile_picture_url	string	멤버 프로필 사진의 URL입니다.
member.member_contact	string	이메일 등 멤버의 연락처입니다.
device_model	string	사진을 촬영한 기기입니다.
custom_notes	array	사진의 사용자 지정 메모입니다. 각 항목에는 title과 content가 있습니다.

자주 하는 실수

• 위도와 경도는 숫자가 아니라 문자열입니다. 연산을 수행하기 전에 형 변환하세요.
• event_id로 중복을 제거하세요. 재시도된 전송은 동일한 event_id를 반복하므로, 이를 저장해 두고 중복 항목은 건너뛰세요.
• 먼저 응답하고 처리는 나중에 하세요. 2xx를 먼저 반환한 다음 무거운 작업을 처리하세요. 그렇지 않으면 전송이 실패로 간주되어 재시도됩니다.

참고 자료

• Webhook 설정하기
• Webhook 이벤트 유형

마지막 업데이트: 2026년 6월 28일