Charges utiles des webhooks d'événements sortants

Cette page documente les charges utiles qu'Almirant envoie à votre serveur via des webhooks d'événements sortants. Elle ne documente pas les webhooks d'agents entrants.

Tous les webhooks d'Almirant envoient des requêtes HTTP POST avec un corps JSON suivant une structure cohérente. Cette page documente le format général et les charges utiles spécifiques à chaque événement.

Format général

Toutes les charges utiles partagent cette structure de base :

{
  "id": "evt_abc123def456",
  "type": "work_item.created",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    // Données spécifiques à l'événement
  }
}

Champ	Type	Description
id	string	Identifiant unique de l'événement
type	string	Type d'événement (voir le tableau des événements ci-dessous)
timestamp	string	Date et heure de l'événement au format ISO 8601 (UTC)
projectId	string	ID du projet où l'événement s'est produit
data	object	Données spécifiques à l'événement

En-têtes HTTP

Chaque requête inclut ces en-têtes :

En-tête	Description	Exemple
Content-Type	Type de contenu	application/json
X-Almirant-Signature	Signature HMAC-SHA256 du corps	a1b2c3d4e5f6...
X-Almirant-Timestamp	Horodatage de l'envoi (epoch Unix en secondes)	1710495000
X-Almirant-Event	Type d'événement	work_item.created
X-Almirant-Delivery	ID unique de livraison sortante pour la déduplication	dlv_xyz789
User-Agent	Identifiant de l'expéditeur	Almirant-Webhooks/1.0

Idempotence des livraisons sortantes

Utilisez X-Almirant-Delivery pour détecter les livraisons sortantes dupliquées. Si deux livraisons ont le même ID, traitez uniquement la première. Il est différent de l'en-tête Idempotency-Key fourni par l'appelant d'un webhook d'agent entrant ; n'intervertissez pas ces deux contrats.

Événements de work items

work_item.created

Se déclenche lorsqu'un nouveau work item est créé dans un board.

{
  "id": "evt_wi_created_001",
  "type": "work_item.created",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "workItem": {
      "id": "wi_abc123",
      "taskId": "MC-T-42",
      "title": "Implementar validacion de formulario de registro",
      "description": "Agregar validacion client-side y server-side al formulario...",
      "type": "task",
      "priority": "high",
      "boardId": "board_xyz",
      "boardColumnId": "col_todo",
      "boardColumnName": "To Do",
      "assigneeId": "user_456",
      "parentId": "wi_parent_789",
      "sprintId": "sprint_001",
      "createdAt": "2025-03-15T10:30:00.000Z"
    }
  }
}

work_item.updated

Se déclenche lorsque des champs d'un work item sont modifiés (titre, description, priorité, assigné, etc.).

{
  "id": "evt_wi_updated_002",
  "type": "work_item.updated",
  "timestamp": "2025-03-15T11:00:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "workItem": {
      "id": "wi_abc123",
      "taskId": "MC-T-42",
      "title": "Implementar validacion de formulario de registro",
      "type": "task",
      "priority": "critical",
      "boardId": "board_xyz",
      "boardColumnId": "col_todo",
      "boardColumnName": "To Do",
      "assigneeId": "user_456",
      "updatedAt": "2025-03-15T11:00:00.000Z"
    },
    "changes": {
      "priority": {
        "from": "high",
        "to": "critical"
      }
    }
  }
}

Le champ changes contient uniquement les champs qui ont changé, avec leur valeur précédente (from) et la nouvelle (to).

work_item.moved

Se déclenche lorsqu'un work item est déplacé entre les colonnes du board (par exemple, de "To Do" à "In Progress").

{
  "id": "evt_wi_moved_003",
  "type": "work_item.moved",
  "timestamp": "2025-03-15T14:20:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "workItem": {
      "id": "wi_abc123",
      "taskId": "MC-T-42",
      "title": "Implementar validacion de formulario de registro",
      "type": "task",
      "boardId": "board_xyz",
      "boardColumnId": "col_in_progress",
      "boardColumnName": "In Progress"
    },
    "move": {
      "fromColumnId": "col_todo",
      "fromColumnName": "To Do",
      "toColumnId": "col_in_progress",
      "toColumnName": "In Progress"
    }
  }
}

work_item.archived

Se déclenche lorsqu'un work item est archivé.

{
  "id": "evt_wi_archived_004",
  "type": "work_item.archived",
  "timestamp": "2025-03-15T16:00:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "workItem": {
      "id": "wi_abc123",
      "taskId": "MC-T-42",
      "title": "Implementar validacion de formulario de registro",
      "type": "task",
      "boardId": "board_xyz",
      "archivedAt": "2025-03-15T16:00:00.000Z"
    }
  }
}

Événements de leads

lead.created

Se déclenche lorsqu'un nouveau lead est créé dans le CRM.

{
  "id": "evt_lead_created_001",
  "type": "lead.created",
  "timestamp": "2025-03-15T09:00:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "lead": {
      "id": "lead_abc123",
      "name": "Maria Garcia",
      "email": "[email protected]",
      "company": "Empresa S.L.",
      "source": "website",
      "tags": ["enterprise", "demo-requested"],
      "createdAt": "2025-03-15T09:00:00.000Z"
    }
  }
}

lead.updated

Se déclenche lorsque les données d'un lead sont mises à jour.

{
  "id": "evt_lead_updated_002",
  "type": "lead.updated",
  "timestamp": "2025-03-15T10:15:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "lead": {
      "id": "lead_abc123",
      "name": "Maria Garcia",
      "email": "[email protected]",
      "company": "Empresa S.L.",
      "source": "website",
      "updatedAt": "2025-03-15T10:15:00.000Z"
    },
    "changes": {
      "company": {
        "from": "Empresa S.L.",
        "to": "Empresa Internacional S.A."
      }
    }
  }
}

lead.stage_changed

Se déclenche lorsqu'un lead change d'étape dans un funnel.

{
  "id": "evt_lead_stage_001",
  "type": "lead.stage_changed",
  "timestamp": "2025-03-15T11:30:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "lead": {
      "id": "lead_abc123",
      "name": "Maria Garcia",
      "email": "[email protected]"
    },
    "funnel": {
      "id": "funnel_xyz",
      "name": "Ventas Enterprise"
    },
    "stageChange": {
      "fromStageId": "stage_discovery",
      "fromStageName": "Discovery",
      "toStageId": "stage_proposal",
      "toStageName": "Proposal"
    }
  }
}

Événements de sprints

sprint.created

Se déclenche lorsqu'un nouveau sprint est créé.

{
  "id": "evt_sprint_created_001",
  "type": "sprint.created",
  "timestamp": "2025-03-15T08:00:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "sprint": {
      "id": "sprint_abc123",
      "name": "Sprint 14",
      "goal": "Completar modulo de facturacion y tests E2E",
      "startDate": "2025-03-15",
      "endDate": "2025-03-29",
      "boardId": "board_xyz",
      "workItemCount": 12,
      "createdAt": "2025-03-15T08:00:00.000Z"
    }
  }
}

sprint.closed

Se déclenche lorsqu'un sprint est fermé.

{
  "id": "evt_sprint_closed_001",
  "type": "sprint.closed",
  "timestamp": "2025-03-29T18:00:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    "sprint": {
      "id": "sprint_abc123",
      "name": "Sprint 14",
      "goal": "Completar modulo de facturacion y tests E2E",
      "startDate": "2025-03-15",
      "endDate": "2025-03-29",
      "closedAt": "2025-03-29T18:00:00.000Z"
    },
    "summary": {
      "totalItems": 12,
      "completedItems": 10,
      "incompleteItems": 2,
      "completionRate": 83.3
    }
  }
}

Récapitulatif des types d'événements

Type d'événement	Entité	Description
work_item.created	Work Item	Nouveau work item créé
work_item.updated	Work Item	Champs du work item modifiés
work_item.moved	Work Item	Work item déplacé entre les colonnes
work_item.archived	Work Item	Work item archivé
lead.created	Lead	Nouveau lead créé
lead.updated	Lead	Données du lead mises à jour
lead.stage_changed	Lead	Le lead change d'étape dans le funnel
sprint.created	Sprint	Nouveau sprint créé
sprint.closed	Sprint	Sprint fermé

Nouveaux événements

Almirant peut ajouter de nouveaux types d'événements à l'avenir. Votre serveur doit ignorer les événements qu'il ne reconnaît pas au lieu d'échouer, afin de maintenir la compatibilité ascendante.