feat: webhooks (#4)

GuptaSiddhant · web-flow · commit c834defee331 · 2026-01-06T03:39:08.000+02:00
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "oxc.oxc-vscode",
+        "typescriptteam.native-preview"
+    ]
+}
diff --git a/package.json b/package.json
@@ -25,7 +25,7 @@
     "lint": "turbo lint",
     "prepare": "husky",
     "release": "node ./scripts/release.ts",
-    "server": "NODE_ENV=development OTEL_DENO=true deno serve -REW --unstable-raw-imports --watch ./scripts/server.ts",
+    "server": "NODE_ENV=development OTEL_DENO=true deno serve -REW --watch ./scripts/server.ts",
     "test": "turbo test",
     "verify": "turbo verify --filter='./packages/*'"
   },
diff --git a/packages/core/deno.json b/packages/core/deno.json
@@ -37,7 +37,6 @@
     "./gcp-firestore": "./dist/gcp-firestore.mjs",
     "./gcp-storage": "./dist/gcp-storage.mjs",
     "./mysql": "./dist/mysql.mjs",
-    "./redis": "./dist/redis.mjs",
-    "./openapi.json": "./openapi.json"
+    "./redis": "./dist/redis.mjs"
   }
 }
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -135,7 +135,6 @@
     "./gcp-storage": "./dist/gcp-storage.mjs",
     "./mysql": "./dist/mysql.mjs",
     "./redis": "./dist/redis.mjs",
-    "./package.json": "./package.json",
-    "./openapi.json": "./openapi.json"
+    "./package.json": "./package.json"
   }
 }
diff --git a/packages/core/src/models/builds-model.ts b/packages/core/src/models/builds-model.ts
@@ -11,6 +11,7 @@ import {
 import { checkAuthorisation } from "../utils/auth.ts";
 import { mimes } from "../utils/mime-utils.ts";
 import { getStore } from "../utils/store.ts";
+import { dispatchWebhooks } from "../utils/webhooks.ts";
 import {
   BuildSchema,
   type BuildCreateType,
@@ -82,6 +83,14 @@ export class BuildsModel extends Model<BuildType> {
       try {
         const projectsModel = new ProjectsModel();
         const project = await projectsModel.get(this.projectId);
+
+        // Do not await, fire and forget
+        dispatchWebhooks("build:created", {
+          projectId: this.projectId,
+          payload: build,
+          projectHooks: project.webhooks,
+        });
+
         if (tags.includes(project.gitHubDefaultBranch)) {
           await projectsModel.update(this.projectId, { latestBuildId: id });
         }
@@ -125,6 +134,13 @@ export class BuildsModel extends Model<BuildType> {
       { ...data, updatedAt: new Date().toISOString() },
       this.dbOptions,
     );
+
+    // Do not await, fire and forget
+    dispatchWebhooks("build:updated", {
+      projectId: this.projectId,
+      payload: data,
+      projectHooks: await new ProjectsModel().getWebhooks(this.projectId),
+    });
   }
 
   async delete(buildId: string, updateTag = true): Promise<void> {
@@ -166,6 +182,14 @@ export class BuildsModel extends Model<BuildType> {
     try {
       const projectsModel = new ProjectsModel();
       const project = await projectsModel.get(this.projectId);
+
+      // Do not await, fire and forget
+      dispatchWebhooks("build:deleted", {
+        projectId: project.id,
+        payload: build,
+        projectHooks: project.webhooks,
+      });
+
       if (project.latestBuildId === buildId) {
         this.debug("Update project for build '%s'", buildId);
         await projectsModel.update(this.projectId, {
diff --git a/packages/core/src/models/projects-model.ts b/packages/core/src/models/projects-model.ts
@@ -5,6 +5,7 @@ import {
   generateStorageContainerId,
 } from "../utils/adapter-utils.ts";
 import { checkAuthorisation } from "../utils/auth.ts";
+import { dispatchWebhooks, type WebhookEntry } from "../utils/webhooks.ts";
 import {
   ProjectSchema,
   type ProjectCreateType,
@@ -87,6 +88,13 @@ export class ProjectsModel extends Model<ProjectType> {
       };
       await this.database.createDocument(this.collectionId, project, this.dbOptions);
 
+      // Do not await, fire and forget
+      dispatchWebhooks("project:created", {
+        projectId: project.id,
+        payload: project,
+        projectHooks: project.webhooks,
+      });
+
       return project;
     } catch (error) {
       throw new HTTPException(500, {
@@ -124,6 +132,13 @@ export class ProjectsModel extends Model<ProjectType> {
       this.dbOptions,
     );
 
+    // Do not await, fire and forget
+    dispatchWebhooks("project:updated", {
+      projectId: id,
+      payload: data,
+      projectHooks: await this.getWebhooks(id),
+    });
+
     if (data.gitHubDefaultBranch) {
       try {
         this.debug("Create default-branch tag '%s'...", data.gitHubDefaultBranch);
@@ -139,10 +154,18 @@ export class ProjectsModel extends Model<ProjectType> {
 
   async delete(id: string): Promise<void> {
     this.log("Delete project '%s'...", id);
+    const project = await this.get(id);
 
     this.debug("Delete project entry '%s' in collection", id);
     await this.database.deleteDocument(this.collectionId, id, this.dbOptions);
 
+    // Do not await, fire and forget
+    dispatchWebhooks("project:deleted", {
+      projectId: id,
+      payload: project,
+      projectHooks: project.webhooks,
+    });
+
     this.debug("Delete project-builds collection");
     await this.database.deleteCollection(
       generateDatabaseCollectionId(id, "Builds"),
@@ -174,4 +197,9 @@ export class ProjectsModel extends Model<ProjectType> {
       update: this.update.bind(this, id),
     };
   };
+
+  async getWebhooks(projectOrId: string | { webhooks?: WebhookEntry[] }): Promise<WebhookEntry[]> {
+    const project = typeof projectOrId === "string" ? await this.get(projectOrId) : projectOrId;
+    return project.webhooks || [];
+  }
 }
diff --git a/packages/core/src/models/projects-schema.ts b/packages/core/src/models/projects-schema.ts
@@ -1,5 +1,6 @@
 import { z } from "@hono/zod-openapi";
 import { DEFAULT_GITHUB_BRANCH, DEFAULT_PURGE_AFTER_DAYS } from "../utils/constants.ts";
+import { WEBHOOK_EVENTS } from "../utils/webhooks.ts";
 import { BuildIdSchema, ProjectIdSchema } from "./~shared-schema.ts";
 
 export { ProjectIdSchema };
@@ -38,6 +39,16 @@ export const ProjectSchema = z
     }),
 
     updatedAt: z.iso.datetime().default(new Date().toISOString()),
+
+    webhooks: z
+      .array(
+        z.object({
+          headers: z.record(z.string(), z.string()).optional(),
+          events: z.array(z.enum(WEBHOOK_EVENTS)).optional(),
+          url: z.url(),
+        }),
+      )
+      .optional(),
   })
   .meta({ id: "Project", title: "StoryBooker project" });
 
diff --git a/packages/core/src/models/tags-model.ts b/packages/core/src/models/tags-model.ts
@@ -2,6 +2,7 @@ import { HTTPException } from "hono/http-exception";
 import type { StoryBookerPermissionAction } from "../adapters/_internal/auth.ts";
 import { generateDatabaseCollectionId } from "../utils/adapter-utils.ts";
 import { checkAuthorisation } from "../utils/auth.ts";
+import { dispatchWebhooks } from "../utils/webhooks.ts";
 import { BuildsModel } from "./builds-model.ts";
 import { ProjectsModel } from "./projects-model.ts";
 import { TagSchema, type TagCreateType, type TagType, type TagUpdateType } from "./tags-schema.ts";
@@ -41,6 +42,13 @@ export class TagsModel extends Model<TagType> {
       };
       await this.database.createDocument(this.collectionId, tag, this.dbOptions);
 
+      // Do not await, fire and forget
+      dispatchWebhooks("tag:updated", {
+        projectId: this.projectId,
+        payload: tag,
+        projectHooks: await new ProjectsModel().getWebhooks(this.projectId),
+      });
+
       return tag;
     } catch (error) {
       throw new HTTPException(500, {
@@ -76,20 +84,35 @@ export class TagsModel extends Model<TagType> {
       { ...data, updatedAt: new Date().toISOString() },
       this.dbOptions,
     );
+
+    // Do not await, fire and forget
+    dispatchWebhooks("tag:updated", {
+      projectId: this.projectId,
+      payload: data,
+      projectHooks: await new ProjectsModel().getWebhooks(this.projectId),
+    });
   }
 
   async delete(id: string): Promise<void> {
     this.log("Delete tag '%s'...", id);
+    const tag = await this.get(id);
 
-    const { gitHubDefaultBranch } = await new ProjectsModel().get(this.projectId);
-    if (id === TagsModel.createId(gitHubDefaultBranch)) {
-      const message = `Cannot delete the tag associated with default branch (${gitHubDefaultBranch}) of the project '${this.projectId}'.`;
+    const project = await new ProjectsModel().get(this.projectId);
+    if (id === TagsModel.createId(project.gitHubDefaultBranch)) {
+      const message = `Cannot delete the tag associated with default branch (${project.gitHubDefaultBranch}) of the project '${this.projectId}'.`;
       this.error(message);
       throw new Error(message);
     }
 
     await this.database.deleteDocument(this.collectionId, id, this.dbOptions);
 
+    // Do not await, fire and forget
+    dispatchWebhooks("tag:updated", {
+      projectId: this.projectId,
+      payload: tag,
+      projectHooks: project.webhooks,
+    });
+
     try {
       this.debug("Delete builds associated with tag '%s'...", id);
       await new BuildsModel(this.projectId).deleteByTag(id, false);
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -5,6 +5,7 @@ import type { LoggerAdapter } from "./adapters/_internal/logger.ts";
 import type { StorageAdapter } from "./adapters/_internal/storage.ts";
 import type { UIAdapter } from "./adapters/_internal/ui.ts";
 import type { ErrorParser } from "./utils/error.ts";
+import type { WebhookEntry } from "./utils/webhooks.ts";
 
 export type {
   StoryBookerUser,
@@ -101,4 +102,8 @@ export interface RouterConfig {
    * Add Hono middlewares to the router before any endpoint is registered/invoked.
    */
   middlewares?: MiddlewareHandler[];
+  /**
+   * Pre-configured webhooks to use for dispatching events (all projects).
+   */
+  webhooks?: WebhookEntry[];
 }
diff --git a/packages/core/src/utils/webhooks.ts b/packages/core/src/utils/webhooks.ts
@@ -0,0 +1,66 @@
+import { getStore } from "./store";
+
+export const WEBHOOK_EVENTS = [
+  "build:created",
+  "build:deleted",
+  "build:updated",
+  "project:created",
+  "project:deleted",
+  "project:updated",
+  "tag:created",
+  "tag:deleted",
+  "tag:updated",
+] as const;
+
+export type WebhookEvent = (typeof WEBHOOK_EVENTS)[number];
+
+/**
+ * Webhook event to their corresponding URL.
+ */
+export interface WebhookEntry {
+  url: string;
+  headers?: Record<string, string>;
+  events?: WebhookEvent[];
+}
+
+export async function dispatchWebhooks(
+  event: WebhookEvent,
+  options: {
+    projectId: string;
+    payload: Record<string, unknown>;
+    timeoutMs?: number;
+    projectHooks?: WebhookEntry[];
+  },
+): Promise<void> {
+  const { logger, config } = getStore();
+  const { projectId, payload, timeoutMs = 5000, projectHooks = [] } = options;
+
+  const configHooks =
+    config?.webhooks?.filter((hook) => !hook.events || hook.events.includes(event)) ?? [];
+  const allHooks = [...configHooks, ...projectHooks];
+
+  if (!allHooks || allHooks.length === 0) {
+    return;
+  }
+
+  // Run in parallel but don't throw — we only want best-effort delivery here
+  await Promise.allSettled(
+    allHooks.map(async (hook) => {
+      const { url, headers } = hook;
+
+      try {
+        const res = await fetch(url, {
+          method: "POST",
+          headers: { ...headers, "content-type": "application/json", "x-webhook-event": event },
+          body: JSON.stringify({ event, projectId, payload }),
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+        logger?.log?.("[webhook] (%s) %s - %s", event, url, res.status);
+        return { url, ok: res.ok, status: res.status };
+      } catch (error) {
+        logger?.error?.("[webhook] ERROR (%s) %s - $s", event, url, error);
+        return { url, ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }),
+  );
+}
diff --git a/scripts/server.ts b/scripts/server.ts
@@ -5,29 +5,41 @@
 
 import { poweredBy } from "hono/powered-by";
 import { timing } from "hono/timing";
-import { createHonoRouter } from "../packages/core/dist/index.mjs";
 import {
   type AuthAdapter,
   type StoryBookerUser,
   StoryBookerPermissionsAllEnabled,
-} from "../packages/core/src/adapters/_internal/auth.ts";
+} from "../packages/core/dist/_internal/adapter/auth.mjs";
 import {
   createLocalFileDatabaseAdapter,
   createLocalFileStorageAdapter,
-} from "../packages/core/src/adapters/fs.ts";
-import { createBasicUIAdapter } from "../packages/ui/src/index.tsx";
+} from "../packages/core/dist/fs.mjs";
+import { createHonoRouter } from "../packages/core/dist/index.mjs";
+import { createBasicUIAdapter } from "../packages/ui/dist/index.mjs";
 
-export default createHonoRouter({
+const router = createHonoRouter({
   auth: createLocalAuthAdapter(),
   config: {
     middlewares: [poweredBy({ serverName: "SBR" }), timing()],
     queueLargeZipFileProcessing: true,
+    webhooks: [
+      {
+        url: "https://webhook.site/d80c03c7-8cd4-49b9-bc13-778736819f3a",
+        headers: { "x-custom-header": "custom-value" },
+      },
+    ],
   },
   database: createLocalFileDatabaseAdapter(".server/db.json"),
   storage: createLocalFileStorageAdapter(".server"),
   ui: createBasicUIAdapter({ logo: "/SBR_white_128.jpg", staticDirs: [".server"] }),
 });
 
+export default router;
+
+// serve({ fetch: router.fetch, port: 8000 }, (info) => {
+//   console.log(`🚀 StoryBooker server running at http://${info.address}:${info.port}`);
+// });
+
 function createLocalAuthAdapter(): AuthAdapter {
   let auth = true;
   let user: StoryBookerUser | null = null;

Original file line number	Diff line number	Diff line change
`@@ -37,7 +37,6 @@`
`37`	`37`	`"./gcp-firestore": "./dist/gcp-firestore.mjs",`
`38`	`38`	`"./gcp-storage": "./dist/gcp-storage.mjs",`
`39`	`39`	`"./mysql": "./dist/mysql.mjs",`
`40`		`- "./redis": "./dist/redis.mjs",`
`41`		`- "./openapi.json": "./openapi.json"`
	`40`	`+ "./redis": "./dist/redis.mjs"`
`42`	`41`	`}`
`43`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -135,7 +135,6 @@`
`135`	`135`	`"./gcp-storage": "./dist/gcp-storage.mjs",`
`136`	`136`	`"./mysql": "./dist/mysql.mjs",`
`137`	`137`	`"./redis": "./dist/redis.mjs",`
`138`		`- "./package.json": "./package.json",`
`139`		`- "./openapi.json": "./openapi.json"`
	`138`	`+ "./package.json": "./package.json"`
`140`	`139`	`}`
`141`	`140`	`}`