Tài liệu tham khảo payload webhook

Khi nào bạn cần làm việc này

Bạn đang viết endpoint nhận webhook của Timemark và cần biết chính xác cấu trúc của request body để có thể phân tích nó.

Cách một lượt gửi dữ liệu được thực hiện

Mỗi lượt gửi dữ liệu là một yêu cầu HTTP POST với một JSON body. Body chứa sự kiện và ảnh liên quan đến sự kiện đó. Endpoint của bạn phải trả về phản hồi 2xx trong thời gian timeout; bất kỳ phản hồi nào khác đều được coi là một lượt gửi thất bại và sẽ được thử gửi lại.

Ví dụ payload

Đây là body được gửi cho một sự kiện Ảnh mới (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"
    }
  ]
}

Tài liệu tham khảo trường dữ liệu

Trường	Loại	Mô tả
event_type	string	Sự kiện đã kích hoạt. photo.uploaded cho sự kiện Ảnh mới.
event_id	string	ID duy nhất cho lượt gửi dữ liệu này. Dùng để loại bỏ trùng lặp khi thử gửi lại.
group_name	string	Đội nhóm mà ảnh thuộc về.
project_name	string	Dự án mà ảnh thuộc về.
photo_code	string	Mã xác minh của ảnh, cũng được dùng trong Trung tâm xác minh ảnh.
photo_name	string	Tên tệp của ảnh, bao gồm thời gian và vị trí chụp.
photo_url	string	URL của ảnh kích thước đầy đủ.
thumbnail_url	string	URL của ảnh thu nhỏ.
photo_timestamp	string	Thời gian chụp theo ISO 8601 (UTC).
photo_location	object	Vị trí chụp. Xem bên dưới.
photo_location.location_name	string	Tên địa điểm hoặc địa chỉ dễ đọc.
photo_location.location_latitude	string	Vĩ độ, dưới dạng chuỗi.
photo_location.location_longitude	string	Kinh độ, dưới dạng chuỗi.
member	object	Thành viên đã chụp ảnh. Xem bên dưới.
member.member_name	string	Tên hiển thị đầy đủ.
member.member_short_name	string	Tên ngắn.
member.member_profile_picture_url	string	URL ảnh đại diện của thành viên.
member.member_contact	string	Thông tin liên hệ của thành viên, ví dụ như email.
device_model	string	Thiết bị đã chụp ảnh.
custom_notes	array	Ghi chú tùy chỉnh trên ảnh. Mỗi mục có một title và content.

Những lỗi thường gặp

• Vĩ độ và kinh độ là chuỗi, không phải số. Hãy ép kiểu chúng trước khi tính toán.
• Loại bỏ trùng lặp dựa trên event_id. Một lượt gửi lại sẽ lặp lại cùng event_id, vì vậy hãy lưu lại và bỏ qua các bản trùng.
• Xác nhận nhanh, xử lý sau. Trả về 2xx trước, rồi mới thực hiện các tác vụ nặng, nếu không lượt gửi sẽ bị coi là thất bại và được thử gửi lại.

Xem thêm

• Cấu hình webhook
• Loại sự kiện webhook

Cập nhật lần cuối: 28 tháng 6, 2026