# How External Services Can Integrate with Kaneo Using Generic Webhooks

> Integrate external services with Kaneo using generic webhooks. Send real-time task event data to your endpoint via HTTP POST payloads for seamless integration.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-29

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/generic-webhook/client.ts)

The resulting JSON payload includes comprehensive context:

```json
{
  "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`](https://github.com/usekaneo/kaneo/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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.