Payloads de webhooks de eventos de saída

Esta página documenta os payloads que o Almirant envia ao seu servidor por meio de webhooks de eventos de saída. Ela não documenta os webhooks de agentes de entrada.

Todos os webhooks do Almirant enviam solicitações HTTP POST com um body JSON que segue uma estrutura consistente. Esta página documenta o formato geral e os payloads específicos de cada evento.

Formato geral

Todos os payloads compartilham esta estrutura 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	Descrição
id	string	Identificador único do evento
type	string	Tipo de evento (veja a tabela de eventos abaixo)
timestamp	string	Data e hora do evento no formato ISO 8601 (UTC)
projectId	string	ID do projeto onde ocorreu o evento
data	object	Dados específicos do evento

Cabeçalhos HTTP

Cada solicitação inclui estes cabeçalhos:

Cabeçalho	Descrição	Exemplo
Content-Type	Tipo de conteúdo	application/json
X-Almirant-Signature	Assinatura HMAC-SHA256 do body	a1b2c3d4e5f6...
X-Almirant-Timestamp	Timestamp do envio (Unix epoch em segundos)	1710495000
X-Almirant-Event	Tipo de evento	work_item.created
X-Almirant-Delivery	ID único da entrega de saída para deduplicação	dlv_xyz789
User-Agent	Identificador do remetente	Almirant-Webhooks/1.0

Idempotência de entregas de saída

Use X-Almirant-Delivery para detectar entregas de saída duplicadas. Se duas entregas tiverem o mesmo ID, processe apenas a primeira. Ele é diferente do cabeçalho Idempotency-Key fornecido por quem chama um webhook de agente de entrada; não misture os dois contratos.

Eventos de Work Items

work_item.created

É acionado quando um novo work item é criado em um 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

É acionado quando campos de um work item são alterados (título, descrição, prioridade, responsável 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"
      }
    }
  }
}

O campo changes contém apenas os campos que foram alterados, com o valor anterior (from) e o novo (to).

work_item.moved

É acionado quando um work item é movido entre as colunas do board, por exemplo, de "To Do" para "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

É acionado quando um work item é arquivado.

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

É acionado quando um novo lead é criado no 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

É acionado quando os dados de um lead são atualizados.

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

É acionado quando um lead muda de etapa dentro de um 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

É acionado quando um novo sprint é criado.

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

É acionado quando um sprint é fechado.

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

Resumo dos tipos de evento

Tipo de evento	Entidade	Descrição
work_item.created	Work Item	Novo work item criado
work_item.updated	Work Item	Campos do work item alterados
work_item.moved	Work Item	Work item movido entre colunas
work_item.archived	Work Item	Work item arquivado
lead.created	Lead	Novo lead criado
lead.updated	Lead	Dados do lead atualizados
lead.stage_changed	Lead	Lead muda de etapa no funnel
sprint.created	Sprint	Novo sprint criado
sprint.closed	Sprint	Sprint fechado

Novos eventos

O Almirant pode adicionar novos tipos de evento no futuro. Seu servidor deve ignorar eventos que não reconhecer, em vez de falhar, para manter compatibilidade futura.