Referência do payload do webhook

Quando fazer isso

Você está escrevendo o endpoint que recebe os webhooks do Timemark e precisa saber o formato exato do corpo da requisição para conseguir fazer o parsing.

Como uma entrega é enviada

Cada entrega é um POST HTTP com um corpo JSON. O corpo carrega o evento e a foto à qual ele se refere. Seu endpoint deve retornar uma resposta 2xx dentro do tempo limite; qualquer outra coisa conta como uma entrega com falha e é reenviada.

Exemplo de payload

Este é o corpo enviado para um evento de Nova 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"
    }
  ]
}

Referência de campos

Campo	Tipo	Descrição
event_type	string	O evento que foi disparado. photo.uploaded para um evento de Nova foto.
event_id	string	ID único desta entrega. Use-o para eliminar duplicatas em novas tentativas.
group_name	string	A equipe à qual a foto pertence.
project_name	string	O projeto ao qual a foto pertence.
photo_code	string	O código de verificação da foto, também usado na Central de Verificação de Fotos.
photo_name	string	O nome do arquivo da foto, incluindo o horário e o local da captura.
photo_url	string	URL da imagem em tamanho completo.
thumbnail_url	string	URL da imagem em miniatura.
photo_timestamp	string	Horário da captura em ISO 8601 (UTC).
photo_location	object	Local da captura. Veja abaixo.
photo_location.location_name	string	Nome do local ou endereço legível para humanos.
photo_location.location_latitude	string	Latitude, como uma string.
photo_location.location_longitude	string	Longitude, como uma string.
member	object	O membro que capturou a foto. Veja abaixo.
member.member_name	string	Nome completo de exibição.
member.member_short_name	string	Nome curto.
member.member_profile_picture_url	string	URL da foto de perfil do membro.
member.member_contact	string	O contato do membro, como um e-mail.
device_model	string	O dispositivo que capturou a foto.
custom_notes	array	Notas personalizadas na foto. Cada item tem um title e um content.

Erros comuns

• Latitude e longitude são strings, não números. Converta-as antes de fazer cálculos.
• Elimine duplicatas usando event_id. Uma entrega reenviada repete o mesmo event_id, então armazene-o e ignore duplicatas.
• Confirme rápido, processe depois. Retorne 2xx primeiro e só depois faça o processamento pesado, ou a entrega será tratada como falha e reenviada.

Veja também

• Configurar um webhook
• Tipos de evento do webhook

Última atualização: 28 de junho de 2026