Webhook-Payload-Referenz

Wann Sie das brauchen

Sie schreiben den Endpunkt, der Timemark-Webhooks empfängt, und müssen die genaue Form des Request-Bodys kennen, um ihn zu parsen.

Wie eine Zustellung gesendet wird

Jede Zustellung ist ein HTTP-POST mit einem JSON-Body. Der Body enthält das Ereignis und das betroffene Foto. Ihr Endpunkt muss innerhalb des Timeouts mit einer 2xx-Antwort antworten; alles andere zählt als fehlgeschlagene Zustellung und wird wiederholt.

Beispiel-Payload

Dies ist der Body, der für ein Neues-Foto-Ereignis gesendet wird (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"
    }
  ]
}

Feldreferenz

Feld	Typ	Beschreibung
event_type	string	Das ausgelöste Ereignis. photo.uploaded für ein Neues-Foto-Ereignis.
event_id	string	Eindeutige ID für diese Zustellung. Damit lassen sich Wiederholungen deduplizieren.
group_name	string	Das Team, zu dem das Foto gehört.
project_name	string	Das Projekt, zu dem das Foto gehört.
photo_code	string	Der Verifizierungscode des Fotos, auch verwendet im Photo Verification Center.
photo_name	string	Der Dateiname des Fotos, einschließlich Aufnahmezeit und -ort.
photo_url	string	URL des Fotos in voller Größe.
thumbnail_url	string	URL des Vorschaubilds.
photo_timestamp	string	Aufnahmezeit in ISO 8601 (UTC).
photo_location	object	Aufnahmeort. Siehe unten.
photo_location.location_name	string	Menschenlesbarer Ortsname oder Adresse.
photo_location.location_latitude	string	Breitengrad, als String.
photo_location.location_longitude	string	Längengrad, als String.
member	object	Das Mitglied, das das Foto aufgenommen hat. Siehe unten.
member.member_name	string	Vollständiger Anzeigename.
member.member_short_name	string	Kurzname.
member.member_profile_picture_url	string	URL des Profilbilds des Mitglieds.
member.member_contact	string	Der Kontakt des Mitglieds, zum Beispiel eine E-Mail-Adresse.
device_model	string	Das Gerät, mit dem das Foto aufgenommen wurde.
custom_notes	array	Benutzerdefinierte Notizen am Foto. Jeder Eintrag hat einen title und content.

Häufige Fallstricke

• Breiten- und Längengrad sind Strings, keine Zahlen. Wandeln Sie sie um, bevor Sie damit rechnen.
• Anhand von event_id deduplizieren. Eine wiederholte Zustellung enthält dieselbe event_id, speichern Sie diese also und überspringen Sie Duplikate.
• Schnell bestätigen, später verarbeiten. Antworten Sie zuerst mit 2xx und erledigen Sie danach aufwendige Verarbeitung, sonst gilt die Zustellung als fehlgeschlagen und wird wiederholt.

Siehe auch

• Einen Webhook konfigurieren
• Webhook-Ereignistypen

Zuletzt aktualisiert: 28. Juni 2026