Formato del Payload

Estructura del payload de webhooks de GitScrum: formato JSON, campos comunes, tipos de recursos y payloads de ejemplo para todas las categorías de eventos.

Todos los payloads de webhook se entregan como JSON vía solicitudes HTTP POST. Esta página documenta la estructura y los campos comunes.

Formato de la Solicitud

Cada entrega de webhook es una solicitud HTTP POST con:

Content-Type: application/json
Cuerpo: Objeto JSON que contiene los datos del recurso

Estructura del Payload

Todos los payloads siguen una estructura de wrapper consistente:

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

El objeto data contiene la representación completa del recurso. Los campos dependen del tipo de evento y del recurso correspondiente.

Recurso de Tarea (BoardTaskResource)

Los eventos de tareas (issues.*) entregan payloads usando el 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 Principales

Campo	Tipo	Descripción
`uuid`	string	Identificador único de la tarea
`title`	string	Título de la tarea
`description`	string	Descripción de la tarea
`type`	object	Tipo de tarea con título y color
`workflow`	object	Columna Kanban actual con título, color, posición
`priority`	object	Nivel de prioridad con título y color
`effort`	object	Estimación de esfuerzo con título y color
`labels`	array	Array de objetos de etiqueta
`users`	array	Usuarios asignados
`config_sprint`	object/null	Sprint asociado
`configuserstory`	object/null	User story asociada
`due_date`	string/null	Fecha de vencimiento en formato YYYY-MM-DD
`stats`	object	Contadores de elementos relacionados
`created_at`	object	Marca de tiempo de creación
`updated_at`	object	Marca de tiempo de última actualización

Recurso de Sprint

Los eventos de sprints (sprints.*) entregan payloads con detalles del 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

Los eventos de user stories (user-stories.*) entregan:

{
  "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 Control de Tiempo

Los eventos de control de tiempo (time-tracking.issues.*) incluyen los detalles del registro de tiempo:

{
  "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 Fecha y Hora

Todas las marcas de tiempo usan un formato consistente:

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

dateforhumans — Cadena de tiempo relativo
timezone — Identificador de zona horaria

Valores Nulos

Los campos sin datos se definen como null:

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

Siempre verifica null antes de acceder a propiedades anidadas.

Relacionado

Tarea Creada — Referencia de eventos de tareas
Seguridad — Encabezados de solicitud y verificación
Buenas Prácticas — Manejo de payloads en producción