How External Services Can Integrate with Kaneo Using Generic Webhooks

External services can integrate with Kaneo by registering a generic webhook integration that sends real-time HTTP POST payloads containing task event data to any specified endpoint.

The Kaneo project management platform exposes a robust plugin architecture that treats external connectivity as a first-class concern. By leveraging the generic-webhook plugin implementation in the API layer, developers can route task lifecycle events—such as creation, status updates, and comments—to custom services without modifying Kaneo’s core codebase.

Plugin Architecture and Event Registration

The generic webhook integration follows the same plugin pattern used for native integrations like GitHub, Gitea, Slack, and Discord. In apps/api/src/plugins/generic-webhook/index.ts, the plugin registers a comprehensive set of handlers for every task-related event.

When a task triggers an event, the corresponding handler in apps/api/src/plugins/generic-webhook/events.ts immediately invokes the sendEvent function. This architecture ensures that external services receive instantaneous notifications without polling the API.

Configuration Schema and Security Validation

Each webhook configuration requires a URL, optional secret for HMAC verification, health metadata, and a per-event enable map. The schema definition resides in apps/api/src/plugins/generic-webhook/config.ts.

The system validates configurations using assertPublicDestination to ensure the target URL is publicly accessible and restricts protocols to HTTP and HTTPS only. This prevents internal network scanning and ensures reliable delivery.

Event Dispatch and Payload Construction

The core dispatch logic implemented in apps/api/src/plugins/generic-webhook/events.ts orchestrates data gathering and transmission. The sendEvent function executes a standardized workflow:

• Retrieves task details via getTaskData and actor information via getActor
• Normalizes the integration configuration using normalizeGenericWebhookConfig
• Constructs a JSON payload containing the event name, timestamps, project context, task details, and actor data
• Transmits the payload via postToGenericWebhook defined in apps/api/src/plugins/generic-webhook/client.ts

The resulting JSON payload includes comprehensive context:

{
  "event": "task.created",
  "timestamp": "2026-08-29T14:32:10.123Z",
  "integration": { "type": "generic-webhook" },
  "project": {
    "id": "proj_abc123",
    "name": "Marketing",
    "workspaceId": "ws_001"
  },
  "task": {
    "id": "task_789",
    "number": 42,
    "title": "Launch new ad campaign",
    "status": "open",
    "statusName": "Open",
    "priority": "high",
    "url": "http://localhost:5173/dashboard/workspace/ws_001/project/proj_abc123/task/task_789"
  },
  "actor": { "id": "user_55", "name": "Alice" },
  "data": {
    "title": "Launch new ad campaign",
    "description": "Create assets and schedule ads",
    "priority": "high",
    "status": "open",
    "number": 42
  }
}

Health Monitoring and Retry Mechanisms

After each delivery attempt, the plugin records success or failure statistics by calling persistWebhookHealth. This function updates the integration row in the database with delivery metadata, enabling the frontend to display real-time webhook health status and supporting future retry logic for failed deliveries.

Due Date Reminders via Scheduled Events

Kaneo extends webhook functionality beyond immediate task events through the scheduler located at apps/api/src/scheduler/project-webhook-reminders.ts. This component invokes sendDueDateReminder for tasks with upcoming due dates, allowing external services to receive proactive reminder callbacks at configurable lead times.

Frontend Integration Management

The web client provides comprehensive CRUD operations for webhook configurations through fetchers located in apps/web/src/fetchers/generic-webhook-integration/. Users can create, update, or delete generic webhook integrations via the UI, with the API persisting configurations in the integration table.

Implementation Examples

To create a generic webhook integration programmatically:

import { createIntegration } from '@kaneo/libs';

await createIntegration({
  projectId: 'proj_abc123',
  type: 'generic-webhook',
  config: {
    webhookUrl: 'https://example.com/kaneo-hook',
    secret: 's3cr3t',
    events: {
      taskCreated: true,
      taskCommentCreated: true,
    },
  },
});

To trigger a due date reminder manually:

import { sendDueDateReminder } from '@kaneo/libs';

await sendDueDateReminder(
  genericWebhookConfig,
  'task_789',
  'proj_abc123',
  60,
  new Date('2026-09-01T10:00:00Z')
);

Summary

• The generic webhook plugin in apps/api/src/plugins/generic-webhook/ enables real-time HTTP notifications for any task event.
• Configuration validation ensures secure delivery to public HTTP/HTTPS endpoints only, with optional HMAC secrets.
• The event dispatch system normalizes task, actor, and project data into structured JSON payloads sent via postToGenericWebhook.
• Health monitoring tracks delivery success through persistWebhookHealth, facilitating reliability improvements.
• Scheduled reminders via apps/api/src/scheduler/project-webhook-reminders.ts support proactive notifications for upcoming due dates.
• Frontend fetchers in apps/web/src/fetchers/generic-webhook-integration/ provide user-friendly CRUD management.

Frequently Asked Questions

What events can trigger a generic webhook in Kaneo?

Kaneo triggers webhooks for comprehensive task lifecycle events including creation, updates, status changes, comments, assignments, and deletions. Additionally, the scheduler invokes sendDueDateReminder for temporal events related to task deadlines.

How does Kaneo secure webhook deliveries to external services?

The system validates URLs using assertPublicDestination to prevent SSRF attacks and supports optional HMAC secrets in the configuration schema. When configured, the postToGenericWebhook function includes signature headers that receiving services can verify to authenticate payloads.

Can I filter which events are sent to my webhook endpoint?

Yes, the configuration schema includes a per-event enable map that allows selective subscription to specific event types. When creating the integration, specify only the events required in the events object to minimize unnecessary traffic and processing.

How does Kaneo handle webhook delivery failures?

The plugin implements health tracking via persistWebhookHealth, which records success and failure states after each delivery attempt. While automatic retries are prepared for in the health metadata structure, the current implementation primarily surfaces health status to the UI for manual intervention and monitoring.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}