مرجع حمولة Webhook

متى تفعل هذا

تكتب نقطة النهاية التي تستقبل عمليات Webhook من Timemark، وتحتاج إلى معرفة الشكل الدقيق لنص الطلب لتتمكن من تحليله.

كيف يُرسَل التسليم

كل تسليم هو طلب HTTP من نوع POST بنص JSON. يحمل النص الحدث والصورة المعنية به. يجب أن تعيد نقطة النهاية الخاصة بك استجابة 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	معرّف فريد لهذا التسليم. استخدمه لإزالة تكرار المحاولات.
group_name	string	الفريق الذي تنتمي إليه الصورة.
project_name	string	المشروع الذي تنتمي إليه الصورة.
photo_code	string	رمز التحقق الخاص بالصورة، يُستخدم أيضًا في مركز التحقق من الصور.
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

آخر تحديث: 28 يونيو 2026