Referencia del payload del webhook

Cuándo hacer esto

Estás escribiendo el endpoint que recibe los webhooks de Timemark y necesitas conocer la forma exacta del cuerpo de la solicitud para poder analizarlo.

Cómo se envía una entrega

Cada entrega es un POST HTTP con un cuerpo JSON. El cuerpo contiene el evento y la foto a la que se refiere. Tu endpoint debe devolver una respuesta 2xx dentro del tiempo de espera; cualquier otra cosa se considera una entrega fallida y se reintenta.

Payload de ejemplo

Este es el cuerpo enviado para un evento Nueva foto (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"
    }
  ]
}

Referencia de campos

Field	Type	Description
event_type	string	El evento que se activó. photo.uploaded para un evento Nueva foto.
event_id	string	ID único para esta entrega. Úsalo para eliminar duplicados en los reintentos.
group_name	string	El equipo al que pertenece la foto.
project_name	string	El proyecto al que pertenece la foto.
photo_code	string	El código de verificación de la foto, también usado en el Centro de verificación de fotos.
photo_name	string	El nombre de archivo de la foto, incluida su hora y ubicación de captura.
photo_url	string	URL de la imagen a tamaño completo.
thumbnail_url	string	URL de la imagen en miniatura.
photo_timestamp	string	Hora de captura en ISO 8601 (UTC).
photo_location	object	Ubicación de captura. Ver más abajo.
photo_location.location_name	string	Nombre del lugar o dirección, legible para humanos.
photo_location.location_latitude	string	Latitud, como string.
photo_location.location_longitude	string	Longitud, como string.
member	object	El miembro que capturó la foto. Ver más abajo.
member.member_name	string	Nombre completo mostrado.
member.member_short_name	string	Nombre corto.
member.member_profile_picture_url	string	URL de la foto de perfil del miembro.
member.member_contact	string	El contacto del miembro, como un correo electrónico.
device_model	string	El dispositivo que capturó la foto.
custom_notes	array	Notas personalizadas en la foto. Cada elemento tiene un title y un content.

Errores comunes

• La latitud y la longitud son strings, no números. Conviértelas antes de hacer cálculos.
• Elimina duplicados usando event_id. Una entrega reintentada repite el mismo event_id, así que guárdalo y omite los duplicados.
• Confirma rápido, procesa después. Devuelve 2xx primero y luego realiza el trabajo pesado, o la entrega se considerará fallida y se reintentará.

Ver también

• Configura un webhook
• Tipos de evento del webhook

Última actualización: 28 de junio de 2026