Format du Payload

Structure du payload des webhooks GitScrum : format JSON, champs communs, types de ressources et payloads d'exemple pour toutes les catégories d'événements.

Tous les payloads de webhook sont livrés en JSON via des requêtes HTTP POST. Cette page documente la structure et les champs communs.

Format de la Requête

Chaque livraison de webhook est une requête HTTP POST avec :

Content-Type : application/json
Corps : Objet JSON contenant les données de la ressource

Structure du Payload

Tous les payloads suivent une structure d'enveloppe cohérente :

{
  "data": {
    // Champs de la ressource
  }
}

L'objet data contient la représentation complète de la ressource. Les champs dépendent du type d'événement et de la ressource correspondante.

Ressource de Tâche (BoardTaskResource)

Les événements de tâches (issues.*) livrent des payloads utilisant le format de ressource 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"
    }
  }
}

Champs Principaux

Champ	Type	Description
`uuid`	string	Identifiant unique de la tâche
`title`	string	Titre de la tâche
`description`	string	Description de la tâche
`type`	object	Type de tâche avec titre et couleur
`workflow`	object	Colonne Kanban actuelle avec titre, couleur, position
`priority`	object	Niveau de priorité avec titre et couleur
`effort`	object	Estimation de l'effort avec titre et couleur
`labels`	array	Tableau d'objets d'étiquettes
`users`	array	Utilisateurs assignés
`config_sprint`	object/null	Sprint associé
`configuserstory`	object/null	User story associée
`due_date`	string/null	Date d'échéance au format YYYY-MM-DD
`stats`	object	Compteurs d'éléments associés
`created_at`	object	Horodatage de création
`updated_at`	object	Horodatage de dernière mise à jour

Ressource de Sprint

Les événements de sprints (sprints.*) livrent des payloads avec les détails du 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"
    }
  }
}

Ressource de User Story

Les événements de user stories (user-stories.*) livrent :

{
  "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"
    }
  }
}

Ressource de Suivi du Temps

Les événements de suivi du temps (time-tracking.issues.*) incluent les détails de l'enregistrement de temps :

{
  "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"
    }
  }
}

Champs de Date et Heure

Tous les horodatages utilisent un format cohérent :

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

dateforhumans — Chaîne de temps relatif
timezone — Identifiant du fuseau horaire

Valeurs Nulles

Les champs sans données sont définis comme null :

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

Vérifiez toujours null avant d'accéder aux propriétés imbriquées.

Associé

Tâche Créée — Référence des événements de tâches
Sécurité — En-têtes de requête et vérification
Bonnes Pratiques — Gestion des payloads en production