Webhook payload 參考

時印相機（Timemark）針對新照片事件所 POST 的 JSON 主體，逐欄位說明。

適用情境

你正在撰寫接收時印相機 webhook 的端點，需要知道請求主體的確切格式，才能正確解析。

傳送方式是什麼

每次傳送都是一個帶有 JSON 主體的 HTTP POST 請求。主體內容包含事件本身，以及該事件所涉及的照片。你的端點必須在逾時前回傳 2xx 回應，否則會被視為傳送失敗並觸發重試。

範例 payload

以下是新照片事件（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	照片所屬的 Project。
`photo_code`	string	照片的驗證碼，也用於照片驗證中心。
`photo_name`	string	照片的檔案名稱，包含拍攝時間與地點。
`photo_url`	string	原始尺寸圖片的網址。
`thumbnail_url`	string	縮圖的網址。
`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	該成員大頭貼的網址。
`member.member_contact`	string	該成員的聯絡方式，例如電子郵件。
`device_model`	string	拍攝這張照片所使用的裝置。
`custom_notes`	array	照片上的自訂備註，每個項目都有 `title` 與 `content`。

常見錯誤

緯度與經度是字串，不是數字。做數學運算前請先轉型。
以 event_id 去除重複。重試的傳送會重複相同的 event_id，請儲存它並略過重複項目。
先確認收到，再處理。先回傳 2xx，再進行耗時的處理，否則這次傳送會被視為失敗並觸發重試。

延伸閱讀

最後更新： 2026年6月28日