Formato do Payload

Estrutura do payload de webhooks do GitScrum: formato JSON, campos comuns, tipos de recursos e payloads de exemplo para todas as categorias de eventos.

Todos os payloads de webhook são entregues como JSON via requisições HTTP POST. Esta página documenta a estrutura e os campos comuns.

Formato da Requisição

Cada entrega de webhook é uma requisição HTTP POST com:

Content-Type: application/json
Body: Objeto JSON contendo os dados do recurso

Estrutura do Payload

Todos os payloads seguem uma estrutura de wrapper consistente:

{
  "data": {
    // Campos do recurso
  }
}

O objeto data contém a representação completa do recurso. Os campos dependem do tipo de evento e do recurso correspondente.

Recurso de Tarefa (BoardTaskResource)

Eventos de tarefas (issues.*) entregam payloads usando o formato de recurso BoardTask:

{
  "data": {
    "uuid": "abc123-def456-ghi789",
    "title": "Task title",
    "description": "Task description in plain text",
    "type": {
      "title": "Feature",
      "color": "#22C55E"
    },
    "workflow": {
      "title": "In Progress",
      "color": "#3B82F6",
      "position": 1
    },
    "priority": {
      "title": "High",
      "color": "#EF4444"
    },
    "effort": {
      "title": "Medium",
      "color": "#F59E0B"
    },
    "labels": [
      {
        "title": "Frontend",
        "color": "#8B5CF6"
      }
    ],
    "users": [
      {
        "username": "johndoe",
        "name": "John Doe",
        "avatar": "https://..."
      }
    ],
    "config_sprint": {
      "title": "Sprint 14"
    },
    "config_user_story": {
      "title": "User authentication"
    },
    "due_date": "2025-01-15",
    "stats": {
      "checklists": 3,
      "comments": 2,
      "attachments": 1,
      "videos": 0,
      "time_trackings": "02:30:00"
    },
    "created_at": {
      "date_for_humans": "2 hours ago",
      "timezone": "UTC"
    },
    "updated_at": {
      "date_for_humans": "5 minutes ago",
      "timezone": "UTC"
    }
  }
}

Campos Principais

Campo	Tipo	Descrição
`uuid`	string	Identificador único da tarefa
`title`	string	Título da tarefa
`description`	string	Descrição da tarefa
`type`	object	Tipo da tarefa com título e cor
`workflow`	object	Coluna Kanban atual com título, cor, posição
`priority`	object	Nível de prioridade com título e cor
`effort`	object	Estimativa de esforço com título e cor
`labels`	array	Array de objetos de label
`users`	array	Usuários atribuídos
`config_sprint`	object/null	Sprint associado
`configuserstory`	object/null	User story associada
`due_date`	string/null	Data de vencimento no formato YYYY-MM-DD
`stats`	object	Contadores de itens relacionados
`created_at`	object	Timestamp de criação
`updated_at`	object	Timestamp da última atualização

Recurso de Sprint

Eventos de sprints (sprints.*) entregam payloads com detalhes do sprint:

{
  "data": {
    "uuid": "sp-abc123-def456",
    "title": "Sprint 14",
    "description": "Authentication module sprint",
    "status": {
      "title": "Open",
      "color": "#22C55E"
    },
    "date_start": "2025-01-06",
    "date_finish": "2025-01-20",
    "time_box": 14,
    "stats": {
      "issues_count": 12,
      "closed_issues_count": 5,
      "effort_total": 34
    },
    "created_at": {
      "date_for_humans": "1 week ago",
      "timezone": "UTC"
    }
  }
}

Recurso de User Story

Eventos de user stories (user-stories.*) entregam:

{
  "data": {
    "uuid": "us-abc123-def456",
    "title": "As a user, I want to reset my password",
    "description": "Password reset via email link",
    "priority": "High",
    "acceptance_criteria": "Given a registered user...",
    "votes_count": 3,
    "is_voted": false,
    "created_at": {
      "date_for_humans": "3 days ago",
      "timezone": "UTC"
    }
  }
}

Recurso de Controle de Tempo

Eventos de controle de tempo (time-tracking.issues.*) incluem os detalhes do registro de tempo:

{
  "data": {
    "uuid": "tt-abc123",
    "started_at": "2025-01-10T09:00:00Z",
    "stopped_at": "2025-01-10T11:30:00Z",
    "duration": "02:30:00",
    "comment": "Worked on API integration",
    "billable": true,
    "user": {
      "username": "johndoe",
      "name": "John Doe"
    }
  }
}

Campos de Data e Hora

Todos os timestamps usam um formato consistente:

{
  "created_at": {
    "date_for_humans": "2 hours ago",
    "timezone": "UTC"
  }
}

dateforhumans — String de tempo relativo
timezone — Identificador do fuso horário

Valores Nulos

Campos sem dados são definidos como null:

{
  "config_sprint": null,
  "config_user_story": null,
  "due_date": null
}

Sempre verifique null antes de acessar propriedades aninhadas.

Relacionado

Tarefa Criada — Referência de eventos de tarefas
Segurança — Cabeçalhos de requisição e verificação
Boas Práticas — Tratamento de payloads em produção