Payloads de webhooks

Todos los webhooks de Almirant envian peticiones HTTP POST con un body JSON que sigue una estructura consistente. Esta pagina documenta el formato general y los payloads especificos de cada evento.

Formato general

Todos los payloads comparten esta estructura base:

{
  "id": "evt_abc123def456",
  "type": "work_item.created",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    // Datos especificos del evento
  }
}

Campo	Tipo	Descripcion
id	string	Identificador unico del evento
type	string	Tipo de evento (ver tabla de eventos abajo)
timestamp	string	Fecha y hora del evento en formato ISO 8601 (UTC)
projectId	string	ID del proyecto donde ocurrio el evento
data	object	Datos especificos del evento

Headers HTTP

Cada peticion incluye estos headers:

Header	Descripcion	Ejemplo
Content-Type	Tipo de contenido	application/json
X-Almirant-Signature	Firma HMAC-SHA256 del body	a1b2c3d4e5f6...
X-Almirant-Timestamp	Timestamp del envio (Unix epoch en segundos)	1710495000
X-Almirant-Event	Tipo de evento	work_item.created
X-Almirant-Delivery	ID unico de esta entrega (para idempotencia)	dlv_xyz789
User-Agent	Identificador del emisor	Almirant-Webhooks/1.0

Idempotencia

Usa el header X-Almirant-Delivery para detectar entregas duplicadas. Si recibes dos peticiones con el mismo ID de delivery, procesa solo la primera.

Eventos de Work Items

work_item.created

Se dispara cuando se crea un nuevo work item en 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 dispara cuando se modifican campos de un work item (titulo, descripcion, prioridad, asignado, 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"
      }
    }
  }
}

El campo changes contiene solo los campos que cambiaron, con su valor anterior (from) y el nuevo (to).

work_item.moved

Se dispara cuando un work item se mueve entre columnas del board (por ejemplo, de "To Do" a "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 dispara cuando se archiva un work item.

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

Eventos de Leads

lead.created

Se dispara cuando se crea un nuevo lead en el 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 dispara cuando se actualizan datos de un lead.

{
  "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 dispara cuando un lead cambia de etapa dentro de 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"
    }
  }
}

Eventos de Sprints

sprint.created

Se dispara cuando se crea un nuevo sprint.

{
  "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 dispara cuando se cierra un sprint.

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

Resumen de tipos de evento

Tipo de evento	Entidad	Descripcion
work_item.created	Work Item	Nuevo work item creado
work_item.updated	Work Item	Campos de work item modificados
work_item.moved	Work Item	Work item movido entre columnas
work_item.archived	Work Item	Work item archivado
lead.created	Lead	Nuevo lead creado
lead.updated	Lead	Datos de lead actualizados
lead.stage_changed	Lead	Lead cambia de etapa en funnel
sprint.created	Sprint	Nuevo sprint creado
sprint.closed	Sprint	Sprint cerrado

Nuevos eventos

Almirant puede agregar nuevos tipos de eventos en el futuro. Tu servidor debe ignorar eventos que no reconozca en lugar de fallar, para mantener compatibilidad hacia adelante.