Ensure that the payload for every task-related webhook event includes enough stable reference data

Feature Discussion
1

For task-related webhook events, please ensure every payload includes enough stable reference data for automation receivers to fetch the full task via the API.

At minimum, every task-related webhook event should include:

  • event name/type
  • task ID, when the event is related to a task
  • project ID, when available
  • comment ID, for task comment events
  • actor/doer ID, when available

Optionally, it would also be helpful to include:

  • task URL
  • project title
  • task title
  • a small resource object with type/id fields, e.g. { "type": "task", "id": 63 }

Motivation

We are using Vikunja webhooks to trigger an automation/agent workflow.

The webhook itself does not need to contain the full expanded task details. Smaller webhook payloads are fine. But the receiver must have a reliable way to go back to Vikunja and fetch the full source-of-truth record through the API:

  • GET /api/v1/tasks/{task_id}
  • GET /api/v1/tasks/{task_id}/comments

If the webhook payload does not include a stable task reference, the receiver has to guess by searching recently updated tasks, titles, timestamps, comments, or project names. That is error-prone and can cause automation to act on the wrong task.

For human notifications, a partial title/comment can be enough. For automation and agent workflows, a deterministic resource reference is important.

Expected behavior

Every task-related webhook event should include a deterministic reference to the affected task.

Examples:

  • task.created → include task.id and project.id
  • task.updated → include task.id and project.id
  • task.comment.created → include task.id, project.id, and comment.id
  • task.assignee.created → include task.id, project.id, and assignee ID
  • task.reminder.fired → include task.id and project.id

Actual concern

Some webhook deliveries may not provide enough information for an automation receiver to unambiguously resolve the related task. This makes webhooks less reliable for agent/task automation use cases.

Environment

  • Vikunja version: v2.3.0
  • Webhooks enabled
  • Project-level webhooks subscribed to task events
  • Use case: webhook triggers an agent which then fetches the full Vikunja task via API before acting

Proposed solution

Guarantee that all task-related webhook payloads contain a minimal stable reference object, for example:

{
  "event": "task.comment.created",
  "task": {
    "id": 63
  },
  "project": {
    "id": 6
  },
  "comment": {
    "id": 26
  }
}

or:

{
  "event": "task.comment.created",
  "resource": {
    "type": "task",
    "id": 63
  },
  "project_id": 6,
  "comment_id": 26
}

This would allow automation receivers to treat the webhook as a signal and Vikunja API as the source of truth.