跳到主要内容

出站事件 Webhook 负载

本页介绍 Almirant 通过出站事件 Webhook 发送到你服务器的负载；不包含入站的智能体 Webhook。

所有 Almirant Webhook 都会发送 HTTP POST 请求，并携带遵循一致结构的 JSON 请求正文。本页说明通用格式及每种事件的特定负载。

通用格式​

所有负载都具有以下基础结构：

{
  "id": "evt_abc123def456",
  "type": "work_item.created",
  "timestamp": "2025-03-15T10:30:00.000Z",
  "projectId": "proj_a1b2c3d4",
  "data": {
    // 事件特定数据
  }
}
字段类型说明
idstring唯一的事件标识符
typestring事件类型（参见下方事件表）
timestampstringISO 8601 格式（UTC）的事件日期和时间
projectIdstring发生事件的项目 ID
dataobject事件特定数据

HTTP 标头​

每个请求都包含以下标头：

标头说明示例
Content-Type内容类型application/json
X-Almirant-Signature请求正文的 HMAC-SHA256 签名a1b2c3d4e5f6...
X-Almirant-Timestamp发送时间戳（Unix 纪元时间，单位为秒）1710495000
X-Almirant-Event事件类型work_item.created
X-Almirant-Delivery唯一的出站投递 ID（用于去重）dlv_xyz789
User-Agent发送方标识符Almirant-Webhooks/1.0
出站投递幂等性

使用 X-Almirant-Delivery 检测重复的出站投递。如果两次投递具有相同的 ID，只处理第一次。它不同于调用方为入站智能体 Webhook 提供的 Idempotency-Key 标头；不要混淆这两个契约。

工作项事件​

work_item.created​

在看板中创建新的工作项时触发。

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

工作项字段被修改时触发（标题、说明、优先级、负责人等）。

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

changes 字段仅包含已更改的字段，以及其原值（from）和新值（to）。

work_item.moved​

工作项在看板列之间移动时触发（例如，从“待办”移动到“进行中”）。

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

工作项归档时触发。

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

潜在客户事件​

lead.created​

在 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​

潜在客户数据更新时触发。

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

潜在客户在漏斗中变更阶段时触发。

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

冲刺事件​

sprint.created​

创建新的冲刺时触发。

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

冲刺关闭时触发。

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

事件类型摘要​

事件类型实体说明
work_item.created工作项创建了新的工作项
work_item.updated工作项工作项字段已修改
work_item.moved工作项工作项在列之间移动
work_item.archived工作项工作项已归档
lead.created潜在客户创建了新的潜在客户
lead.updated潜在客户潜在客户数据已更新
lead.stage_changed潜在客户潜在客户在漏斗中变更阶段
sprint.created冲刺创建了新的冲刺
sprint.closed冲刺冲刺已关闭
新事件

Almirant 未来可能会添加新的事件类型。为保持前向兼容性，你的服务器应忽略无法识别的事件，而不是因此失败。