Nutzdaten ausgehender Ereignis-Webhooks

Diese Seite dokumentiert die Nutzdaten, die Almirant über ausgehende Ereignis-Webhooks an deinen Server sendet. Sie dokumentiert nicht die eingehenden Agenten-Webhooks.

Alle Almirant-Webhooks senden HTTP-POST-Anfragen mit einem JSON-Body, der einer konsistenten Struktur folgt. Diese Seite dokumentiert das allgemeine Format und die spezifischen Payloads für jedes Ereignis.

Allgemeines Format

Alle Payloads haben diese Basisstruktur:

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

Feld	Typ	Beschreibung
id	string	Eindeutige Kennung des Ereignisses
type	string	Ereignistyp (siehe Ereignistabelle unten)
timestamp	string	Datum und Uhrzeit des Ereignisses im Format ISO 8601 (UTC)
projectId	string	ID des Projekts, in dem das Ereignis aufgetreten ist
data	object	Ereignisspezifische Daten

HTTP-Header

Jede Anfrage enthält diese Header:

Header	Beschreibung	Beispiel
Content-Type	Inhaltstyp	application/json
X-Almirant-Signature	HMAC-SHA256-Signatur des Bodys	a1b2c3d4e5f6...
X-Almirant-Timestamp	Zeitstempel des Versands (Unix-Epoch in Sekunden)	1710495000
X-Almirant-Event	Ereignistyp	work_item.created
X-Almirant-Delivery	Eindeutige ID der ausgehenden Zustellung zur Deduplizierung	dlv_xyz789
User-Agent	Kennung des Absenders	Almirant-Webhooks/1.0

Idempotenz ausgehender Zustellungen

Verwende X-Almirant-Delivery, um doppelte ausgehende Zustellungen zu erkennen. Wenn zwei Zustellungen dieselbe ID haben, verarbeite nur die erste. Dies unterscheidet sich vom Header Idempotency-Key, den der Aufrufer eines eingehenden Agenten-Webhooks bereitstellt; vertausche diese beiden Verträge nicht.

Work-Item-Ereignisse

work_item.created

Wird ausgelöst, wenn ein neues Work Item auf einem Board erstellt wird.

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

Wird ausgelöst, wenn Felder eines Work Items geändert werden (Titel, Beschreibung, Priorität, Zuweisung usw.).

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

Das Feld changes enthält nur die Felder, die sich geändert haben, mit ihrem vorherigen Wert (from) und dem neuen Wert (to).

work_item.moved

Wird ausgelöst, wenn ein Work Item zwischen Spalten des Boards verschoben wird (zum Beispiel von "To Do" zu "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

Wird ausgelöst, wenn ein Work Item archiviert wird.

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

lead.created

Wird ausgelöst, wenn ein neuer Lead im CRM erstellt wird.

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

Wird ausgelöst, wenn Daten eines Leads aktualisiert werden.

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

Wird ausgelöst, wenn ein Lead die Phase innerhalb eines Funnels wechselt.

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

sprint.created

Wird ausgelöst, wenn ein neuer Sprint erstellt wird.

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

Wird ausgelöst, wenn ein Sprint geschlossen wird.

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

Übersicht der Ereignistypen

Ereignistyp	Entität	Beschreibung
work_item.created	Work Item	Neues Work Item erstellt
work_item.updated	Work Item	Felder des Work Items geändert
work_item.moved	Work Item	Work Item zwischen Spalten verschoben
work_item.archived	Work Item	Work Item archiviert
lead.created	Lead	Neuer Lead erstellt
lead.updated	Lead	Lead-Daten aktualisiert
lead.stage_changed	Lead	Lead wechselt die Phase im Funnel
sprint.created	Sprint	Neuer Sprint erstellt
sprint.closed	Sprint	Sprint geschlossen

Neue Ereignisse

Almirant kann künftig neue Ereignistypen hinzufügen. Dein Server sollte Ereignisse, die er nicht erkennt, ignorieren, anstatt einen Fehler zu verursachen, um Vorwärtskompatibilität zu gewährleisten.