Webhook Payloads

All Almirant webhooks send HTTP POST requests with a JSON body that follows a consistent structure. This page documents the general format and the specific payloads for each event.

General format

All payloads share this base structure:

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

Field	Type	Description
id	string	Unique event identifier
type	string	Event type (see event table below)
timestamp	string	Event date and time in ISO 8601 format (UTC)
projectId	string	ID of the project where the event occurred
data	object	Event-specific data

HTTP Headers

Each request includes these headers:

Header	Description	Example
Content-Type	Content type	application/json
X-Almirant-Signature	HMAC-SHA256 signature of the body	a1b2c3d4e5f6...
X-Almirant-Timestamp	Sending timestamp (Unix epoch in seconds)	1710495000
X-Almirant-Event	Event type	work_item.created
X-Almirant-Delivery	Unique delivery ID (for idempotency)	dlv_xyz789
User-Agent	Sender identifier	Almirant-Webhooks/1.0

Idempotency

Use the X-Almirant-Delivery header to detect duplicate deliveries. If you receive two requests with the same delivery ID, process only the first one.

Work Item Events

work_item.created

Triggered when a new work item is created on a 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

Triggered when fields of a work item are modified (title, description, priority, assignee, 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"
      }
    }
  }
}

The changes field contains only the fields that changed, with their previous value (from) and the new one (to).

work_item.moved

Triggered when a work item is moved between board columns (for example, from "To Do" to "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

Triggered when a work item is 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 Events

lead.created

Triggered when a new lead is created in the 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

Triggered when lead data is 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

Triggered when a lead changes stage within a 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"
    }
  }
}

Sprint Events

sprint.created

Triggered when a new sprint is 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

Triggered when a sprint is 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
    }
  }
}

Event type summary

Event type	Entity	Description
work_item.created	Work Item	New work item created
work_item.updated	Work Item	Work item fields modified
work_item.moved	Work Item	Work item moved between columns
work_item.archived	Work Item	Work item archived
lead.created	Lead	New lead created
lead.updated	Lead	Lead data updated
lead.stage_changed	Lead	Lead changed stage in funnel
sprint.created	Sprint	New sprint created
sprint.closed	Sprint	Sprint closed

New events

Almirant may add new event types in the future. Your server should ignore unrecognized events rather than failing, to maintain forward compatibility.