⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import { randomUUID } from 'node:crypto';
import { aiAgent, db, user, webhook, webhookDelivery } from '@repo/db';
import { and, eq, sql } from 'drizzle-orm';
import type { ActivityActor } from '#modules/issues/activity';
import type { WebhookEventType } from './service';
// Maps our granular event type to the Linear-style envelope's action + resource
// type. action is create | update | remove. type is the PascalCase resource.
// Linear's action/type pair cannot distinguish our assigned, state_changed, and
// label_changed variants, because all of them are an issue update. The payload keeps
// the granular event in its own `event` field.
const EVENT_SHAPE: Record<WebhookEventType, { action: string; type: string }> = {
'issue.created': { action: 'create', type: 'Issue' },
'issue.updated': { action: 'update', type: 'Issue' },
'issue.deleted': { action: 'remove', type: 'Issue' },
'issue.assigned': { action: 'update', type: 'Issue' },
'issue.state_changed': { action: 'update', type: 'Issue' },
'issue.label_changed': { action: 'update', type: 'Issue' },
'issue.link_changed': { action: 'update', type: 'Issue' },
'comment.created': { action: 'create', type: 'Comment' },
'comment.updated': { action: 'update', type: 'Comment' },
'comment.deleted': { action: 'remove', type: 'Comment' },
'agent_run.finished': { action: 'update', type: 'AgentRun' },
};
// Who caused the event. An agent acts through its own bot user, so a user id is an
// agent when an ai_agent row points at it. A system write has no user: it carries
// the system's name ('GitHub', 'Auto-archive'), or null for an unnamed one.
interface WebhookActor {
type: 'human' | 'agent' | 'system';
id: string | null;
name: string | null;
}
async function resolveActor(actor: ActivityActor): Promise<WebhookActor> {
if (!actor) return { type: 'system', id: null, name: null };
if (typeof actor === 'object') return { type: 'system', id: null, name: actor.system };
const [row] = await db
.select({ name: user.name, agentId: aiAgent.id })
.from(user)
.leftJoin(aiAgent, eq(aiAgent.userId, user.id))
.where(eq(user.id, actor))
.limit(1);
return { type: row?.agentId != null ? 'agent' : 'human', id: actor, name: row?.name ?? null };
}
export interface ProjectEvent {
projectId: number;
type: WebhookEventType;
actor: ActivityActor;
// The event's webhook payloads (`data`), one per issue, comment or run it covers. Built on
// the first call and shared with the webhooks.
load: () => Promise<unknown[]>;
}
type ProjectEventListener = (event: ProjectEvent) => Promise<void>;
const listeners: ProjectEventListener[] = [];
// Hands the events the webhooks get to an extension of the api, inside the request or
// the run that caused them. A listener that throws is logged and does not fail it.
// Returns the call that removes the listener.
export function onProjectEvent(listener: ProjectEventListener): () => void {
listeners.push(listener);
return () => {
const at = listeners.indexOf(listener);
if (at >= 0) listeners.splice(at, 1);
};
}
// Whether a listener of onProjectEvent or a subscribed webhook takes eventType, for a
// caller that has to build the payloads before its write removes what they name.
export async function projectEventWanted(
projectId: number,
eventType: WebhookEventType,
): Promise<boolean> {
return listeners.length > 0 || (await subscribedWebhooks(projectId, eventType)).length > 0;
}
// The active webhooks of the project that subscribe to eventType.
function subscribedWebhooks(projectId: number, eventType: WebhookEventType) {
return db
.select({ id: webhook.id })
.from(webhook)
.where(
and(
eq(webhook.projectId, projectId),
eq(webhook.isActive, true),
// events is a jsonb array of event-type strings. @> tests membership.
sql`${webhook.events} @> ${JSON.stringify([eventType])}::jsonb`,
),
);
}
// Fan-out for outgoing webhooks. Queues one delivery per active webhook of the
// project that subscribes to eventType, for each payload `load` returns. Each event
// gets its own eventId, shared by its deliveries and kept across retries so a
// receiver can deduplicate; the deliveries go in as one insert. Call it right after a
// domain mutation, next to the activity log. The payloads are built at most once, when a
// listener of onProjectEvent or a subscribed webhook needs them, so a project with no
// webhooks and no listener pays one indexed SELECT.
//
// The body follows Linear's webhook envelope: top-level action, type, actor, data,
// plus createdAt and webhookTimestamp (epoch ms). `event` is our extension, and it
// carries the granular event type. We omit organizationId, because there is no
// organization concept. The shared dedup id goes in the X-Itsaplan-Event-Id header,
// not in the body.
export async function emitWebhookEvents(
projectId: number,
eventType: WebhookEventType,
load: () => Promise<unknown[]>,
actor: ActivityActor,
): Promise<void> {
let loaded: Promise<unknown[]> | undefined;
const loadOnce = () => (loaded ??= load());
for (const listener of listeners) {
try {
await listener({ projectId, type: eventType, actor, load: loadOnce });
} catch (error) {
console.error('[webhooks] event listener failed:', error);
}
}
const matching = await subscribedWebhooks(projectId, eventType);
if (matching.length === 0) return;
const payloads = await loadOnce();
if (payloads.length === 0) return;
const { action, type } = EVENT_SHAPE[eventType];
const resolvedActor = await resolveActor(actor);
const now = new Date();
const createdAt = now.toISOString();
const webhookTimestamp = now.getTime();
await db.insert(webhookDelivery).values(
payloads.flatMap((data) => {
const eventId = randomUUID();
return matching.map((h) => ({
webhookId: h.id,
eventId,
eventType,
payload: {
action,
type,
event: eventType,
actor: resolvedActor,
createdAt,
data,
webhookTimestamp,
webhookId: h.id,
},
}));
}),
);
}