⭐️⭐️⭐️ 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 { randomBytes } from 'node:crypto';
import { db, webhook, webhookDelivery } from '@repo/db';
import { and, desc, eq, lt } from 'drizzle-orm';
import { iso } from '#shared/lib';
// Outgoing webhook subscriptions on a project. A subscription targets a `url` and
// lists the event types it wants. It carries its own `secret`, which signs the
// payloads sent to that url. This layer only stores and returns the subscription.
// The delivery side is separate.
// The event types a subscription can select. Keep this list in sync with the events
// emitted through modules/issues/webhook-payload.ts and modules/agents/core/run-finished.ts,
// and with the frontend list (apps/web src/lib/api/endpoints/webhooks.ts).
//
// issue.updated fires on any field change, archiving and restoring included. The
// granular issue.assigned, issue.state_changed, and issue.label_changed fire in
// addition, and only when that specific field changes on an existing issue. issue.state_changed fires when the
// issue moves to a different state (column). issue.link_changed fires for both issues
// of an added or removed relation, and without issue.updated: no field of either
// issue changed.
export const WEBHOOK_EVENT_TYPES = [
'issue.created',
'issue.updated',
'issue.deleted',
'issue.assigned',
'issue.state_changed',
'issue.label_changed',
'issue.link_changed',
'comment.created',
// An edit changes a comment's body; a delete removes the comment and its replies.
// Both carry the comment as their payload, and neither fires comment.created
// again for the replies a delete takes with it.
'comment.updated',
'comment.deleted',
// A run of an agent in the project ended: success, failed or canceled. Its payload is
// the run (modules/agents/core/run-finished.ts).
'agent_run.finished',
] as const;
export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
export interface WebhookRow {
id: number;
projectId: number;
url: string;
secret: string;
events: WebhookEventType[];
isActive: boolean;
createdAt: string;
}
function mapWebhook(row: typeof webhook.$inferSelect): WebhookRow {
return {
id: row.id,
projectId: row.projectId,
url: row.url,
secret: row.secret,
events: (row.events as WebhookEventType[]) ?? [],
isActive: row.isActive,
createdAt: iso(row.createdAt),
};
}
// A signing secret for a new subscription. The server generates it, and never derives
// it from user input.
export function generateSecret(): string {
return `whsec_${randomBytes(24).toString('hex')}`;
}
export async function listWebhooks(projectId: number): Promise<WebhookRow[]> {
const rows = await db
.select()
.from(webhook)
.where(eq(webhook.projectId, projectId))
.orderBy(webhook.id);
return rows.map(mapWebhook);
}
export async function createWebhook(input: {
projectId: number;
url: string;
events: WebhookEventType[];
isActive?: boolean;
}): Promise<WebhookRow> {
const [row] = await db
.insert(webhook)
.values({
projectId: input.projectId,
url: input.url,
secret: generateSecret(),
events: input.events,
isActive: input.isActive ?? true,
})
.returning();
return mapWebhook(row);
}
export async function getWebhook(id: number): Promise<WebhookRow | null> {
const rows = await db.select().from(webhook).where(eq(webhook.id, id));
return rows[0] ? mapWebhook(rows[0]) : null;
}
// Updates only the fields the patch provides. The secret changes only through rotation.
export async function updateWebhook(
id: number,
patch: { url?: string; events?: WebhookEventType[]; isActive?: boolean },
): Promise<WebhookRow | null> {
const set: Partial<typeof webhook.$inferInsert> = {};
if (patch.url !== undefined) set.url = patch.url;
if (patch.events !== undefined) set.events = patch.events;
if (patch.isActive !== undefined) set.isActive = patch.isActive;
// The worker keeps a webhook active while its consecutive failures stay under the
// disable threshold, and clears that counter only on a delivery that succeeds. A
// webhook switched back on therefore starts at the threshold, and its next failed
// attempt disables it again, so turning it on clears the counter with it.
if (patch.isActive === true) set.consecutiveFailures = 0;
if (Object.keys(set).length === 0) return getWebhook(id);
const [row] = await db.update(webhook).set(set).where(eq(webhook.id, id)).returning();
return row ? mapWebhook(row) : null;
}
// Deliveries are signed when they are sent, so a retry queued before the rotation is
// signed with the new secret too.
export async function rotateWebhookSecret(id: number): Promise<WebhookRow | null> {
const [row] = await db
.update(webhook)
.set({ secret: generateSecret() })
.where(eq(webhook.id, id))
.returning();
return row ? mapWebhook(row) : null;
}
export async function deleteWebhook(id: number): Promise<void> {
await db.delete(webhook).where(eq(webhook.id, id));
}
// --- Delivery history ------------------------------------------------------------
export interface WebhookDeliveryRow {
id: number;
eventId: string;
eventType: string;
status: string;
attempts: number;
// The payload we sent (the request body), for the "sent" view.
payload: unknown;
responseStatus: number | null;
responseBody: string | null;
lastError: string | null;
nextAttemptAt: string;
createdAt: string;
}
export interface WebhookDeliveryPage {
items: WebhookDeliveryRow[];
// The id to pass as `before` to load the next page, or null on the last page.
nextCursor: number | null;
}
function mapDelivery(row: typeof webhookDelivery.$inferSelect): WebhookDeliveryRow {
return {
id: row.id,
eventId: row.eventId,
eventType: row.eventType,
status: row.status,
attempts: row.attempts,
payload: row.payload,
responseStatus: row.responseStatus,
responseBody: row.responseBody,
lastError: row.lastError,
nextAttemptAt: iso(row.nextAttemptAt),
createdAt: iso(row.createdAt),
};
}
// One page of the webhook's deliveries, newest first. Keyset pagination by id, which
// works because delivery ids only grow: pass the previous page's nextCursor as
// `before` to get the next page. This clamps limit to 1..50.
export async function listWebhookDeliveries(
webhookId: number,
opts: { before?: number; limit?: number } = {},
): Promise<WebhookDeliveryPage> {
const limit = Math.min(Math.max(opts.limit ?? 25, 1), 50);
const rows = await db
.select()
.from(webhookDelivery)
.where(
and(
eq(webhookDelivery.webhookId, webhookId),
opts.before ? lt(webhookDelivery.id, opts.before) : undefined,
),
)
.orderBy(desc(webhookDelivery.id))
.limit(limit + 1);
const hasMore = rows.length > limit;
const page = hasMore ? rows.slice(0, limit) : rows;
return {
items: page.map(mapDelivery),
nextCursor: hasMore ? page[page.length - 1].id : null,
};
}