Webhook payload reference

When you’d do this

You’re writing the endpoint that receives Timemark webhooks and need to know the exact shape of the request body so you can parse it.

How a delivery is sent

Each delivery is an HTTP POST with a JSON body. The body carries the event and the photo it concerns. Your endpoint must return a 2xx response within the timeout; anything else counts as a failed delivery and is retried.

Example payload

This is the body sent for a New photo event (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"
    }
  ]
}

Field reference

Field	Type	Description
event_type	string	The event that fired. photo.uploaded for a New photo event.
event_id	string	Unique ID for this delivery. Use it to de-duplicate retries.
group_name	string	The team the photo belongs to.
project_name	string	The project the photo belongs to.
photo_code	string	The photo’s verification code, also used in the Photo Verification Center.
photo_name	string	The photo’s file name, including its capture time and location.
photo_url	string	URL of the full-size image.
thumbnail_url	string	URL of the thumbnail image.
photo_timestamp	string	Capture time in ISO 8601 (UTC).
photo_location	object	Capture location. See below.
photo_location.location_name	string	Human-readable place name or address.
photo_location.location_latitude	string	Latitude, as a string.
photo_location.location_longitude	string	Longitude, as a string.
member	object	The member who captured the photo. See below.
member.member_name	string	Full display name.
member.member_short_name	string	Short name.
member.member_profile_picture_url	string	URL of the member’s profile picture.
member.member_contact	string	The member’s contact, such as an email.
device_model	string	The device that captured the photo.
custom_notes	array	Custom notes on the photo. Each item has a title and content.

Common pitfalls

• Latitude and longitude are strings, not numbers. Cast them before doing math.
• De-duplicate on event_id. A retried delivery repeats the same event_id, so store it and skip duplicates.
• Acknowledge fast, process later. Return 2xx first, then do heavy work, or the delivery is treated as failed and retried.

See also

• Configure a webhook
• Webhook event types

Last updated: June 28, 2026