feat: Add webhook sender worker for delivering event notifications

docker-compose.dev.yml

@@ -158,6 +158,18 @@ services:
       - ./:/usr/src/app
       - workers-deps:/usr/src/app/node_modules
 
+  hawk-worker-webhook:
+    build:
+      dockerfile: "dev.Dockerfile"
+      context: .
+    env_file:
+      - .env
+    restart: unless-stopped
+    entrypoint: yarn run-webhook
+    volumes:
+      - ./:/usr/src/app
+      - workers-deps:/usr/src/app/node_modules
+
 volumes:
   workers-deps:
 

package.json

@@ -1,7 +1,7 @@
 {
     "name": "hawk.workers",
     "private": true,
-    "version": "0.1.2",
+    "version": "0.1.3",
     "description": "Hawk workers",
     "repository": "git@github.com:codex-team/hawk.workers.git",
     "license": "BUSL-1.1",
@@ -34,6 +34,7 @@
         "test:notifier": "jest workers/notifier",
         "test:js": "jest workers/javascript",
         "test:task-manager": "jest workers/task-manager",
+        "test:webhook": "jest workers/webhook",
         "test:clear": "jest --clearCache",
         "run-default": "yarn worker hawk-worker-default",
         "run-sentry": "yarn worker hawk-worker-sentry",
@@ -49,13 +50,14 @@
         "run-email": "yarn worker hawk-worker-email",
         "run-telegram": "yarn worker hawk-worker-telegram",
         "run-limiter": "yarn worker hawk-worker-limiter",
-        "run-task-manager": "yarn worker hawk-worker-task-manager"
+        "run-task-manager": "yarn worker hawk-worker-task-manager",
+        "run-webhook": "yarn worker hawk-worker-webhook"
     },
     "dependencies": {
         "@babel/parser": "^7.26.9",
         "@babel/traverse": "7.26.9",
         "@hawk.so/nodejs": "^3.1.1",
-        "@hawk.so/types": "^0.5.7",
+        "@hawk.so/types": "^0.5.9",
         "@types/amqplib": "^0.8.2",
         "@types/jest": "^29.5.14",
         "@types/mongodb": "^3.5.15",

workers/email/tests/provider.test.ts

@@ -10,7 +10,7 @@ nodemailerMock.createTransport = jest.fn(() => ({
 
 jest.mock('nodemailer', () => nodemailerMock);
 
-import { DecodedGroupedEvent, ProjectDBScheme } from '@hawk.so/types';
+import { DecodedGroupedEvent, ProjectDBScheme, UserDBScheme } from '@hawk.so/types';
 import '../src/env';
 import EmailProvider from '../src/provider';
 import Templates from '../src/templates/names';
@@ -187,6 +187,11 @@ describe('EmailProvider', () => {
           password: '$argon2i$v=19$m=4096,t=3,p=1$QOo3u8uEor0t+nqCLpEW3g$aTCDEaHht9ro9VZDD1yZGpaTi+g1OWsfHbYd5TQBRPs',
           name: 'Hahahawk',
         },
+        assignee: {
+          _id: new ObjectId('5ec3ffe769c0030022f88f25'),
+          email: 'assignee@email.ru',
+          name: 'Assignee User',
+        } as UserDBScheme,
         project: {
           _id: new ObjectId('5d206f7f9aaf7c0071d64596'),
           token: 'project-token',

workers/notifier/types/channel.ts

@@ -6,6 +6,7 @@ export enum ChannelType {
   Telegram = 'telegram',
   Slack = 'slack',
   Loop = 'loop',
+  Webhook = 'webhook',
 }
 
 /**

workers/sender/src/index.ts

@@ -253,6 +253,7 @@ export default abstract class SenderWorker extends Worker {
         project,
         event,
         whoAssigned,
+        assignee,
         daysRepeated,
       },
     } as AssigneeNotification);

workers/sender/types/template-variables/assignee.ts

@@ -21,6 +21,11 @@ export interface AssigneeTemplateVariables extends CommonTemplateVariables {
    */
   whoAssigned: UserDBScheme;
 
+  /**
+   * User who was assigned to resolve the event
+   */
+  assignee: UserDBScheme;
+
   /**
    * Number of event repetitions
    */

workers/webhook/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "hawk-worker-webhook",
+  "version": "1.0.0",
+  "description": "Webhook sender worker — delivers event notifications as JSON POST requests",
+  "main": "src/index.ts",
+  "license": "MIT",
+  "workerType": "sender/webhook",
+  "scripts": {
+    "test": "jest"
+  }
+}

workers/webhook/src/deliverer.ts

@@ -0,0 +1,125 @@
+import https from 'https';
+import http from 'http';
+import { createLogger, format, Logger, transports } from 'winston';
+import { WebhookDelivery } from '../types/template';
+import { HttpStatusCode, MS_IN_SEC } from '../../../lib/utils/consts';
+
+/**
+ * How many seconds to wait for a webhook response before aborting
+ */
+const DELIVERY_TIMEOUT_SEC = 10;
+
+/**
+ * Timeout for webhook delivery in milliseconds
+ */
+const DELIVERY_TIMEOUT_MS = MS_IN_SEC * DELIVERY_TIMEOUT_SEC;
+
+/**
+ * Deliverer sends JSON POST requests to external webhook endpoints.
+ *
+ * SSRF validation is performed at the API layer when the endpoint is saved —
+ * this class trusts the stored URL and only handles delivery.
+ */
+export default class WebhookDeliverer {
+  /**
+   * Logger module
+   * (default level='info')
+   */
+  private logger: Logger = createLogger({
+    level: process.env.LOG_LEVEL || 'info',
+    transports: [
+      new transports.Console({
+        format: format.combine(
+          format.timestamp(),
+          format.colorize(),
+          format.simple(),
+          format.printf((msg) => `${msg.timestamp} - ${msg.level}: ${msg.message}`)
+        ),
+      }),
+    ],
+  });
+
+  /**
+   * Sends webhook delivery to the endpoint via HTTP POST.
+   * Adds X-Hawk-Notification header with the notification type (similar to GitHub's X-GitHub-Event).
+   *
+   * @param endpoint - URL to POST to
+   * @param delivery - webhook delivery { type, payload }
+   */
+  public async deliver(endpoint: string, delivery: WebhookDelivery): Promise<void> {
+    let url: URL;
+
+    try {
+      url = new URL(endpoint);
+    } catch {
+      this.logger.log('error', `Webhook delivery skipped — invalid URL: ${endpoint}`);
+
+      return;
+    }
+
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+      this.logger.log('error', `Webhook delivery skipped — unsupported protocol: ${url.protocol}`);
+
+      return;
+    }
+
+    const body = JSON.stringify(delivery);
+    const transport = url.protocol === 'https:' ? https : http;
+
+    return new Promise<void>((resolve) => {
+      const req = transport.request(
+        url,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Hawk-Webhook/1.0',
+            'X-Hawk-Notification': delivery.type,
+            'Content-Length': Buffer.byteLength(body),
+          },
+          timeout: DELIVERY_TIMEOUT_MS,
+        },
+        (res) => {
+          res.resume();
+
+          const status = res.statusCode || 0;
+
+          const isRedirect = (
+            status === HttpStatusCode.MovedPermanently ||
+            status === HttpStatusCode.Found ||
+            status === HttpStatusCode.SeeOther ||
+            status === HttpStatusCode.TemporaryRedirect ||
+            status === HttpStatusCode.PermanentRedirect
+          ) && res.headers.location;
+
+          if (isRedirect) {
+            this.logger.log('error', `Webhook blocked — redirect ${status} to ${res.headers.location} from ${endpoint}`);
+            resolve();
+
+            return;
+          }
+
+          if (status >= HttpStatusCode.BadRequest) {
+            this.logger.log('error', `Webhook delivery failed: ${status} ${res.statusMessage} for ${endpoint}`);
+          }
+
+          resolve();
+        }
+      );
+
+      req.on('error', (e) => {
+        this.logger.log('error', `Can't deliver webhook to ${endpoint}: ${e.message}`);
+        resolve();
+      });
+
+      req.on('timeout', () => {
+        this.logger.log('error', `Webhook delivery timed out for ${endpoint}`);
+        req.destroy();
+        resolve();
+      });
+
+      req.write(body);
+      req.end();
+    });
+  }
+}

workers/webhook/src/index.ts

@@ -0,0 +1,24 @@
+import * as pkg from './../package.json';
+import WebhookProvider from './provider';
+import SenderWorker from 'hawk-worker-sender/src';
+import { ChannelType } from 'hawk-worker-notifier/types/channel';
+
+/**
+ * Worker to send webhook notifications
+ */
+export default class WebhookSenderWorker extends SenderWorker {
+  /**
+   * Worker type
+   */
+  public readonly type: string = pkg.workerType;
+
+  /**
+   * Webhook channel type
+   */
+  protected channelType = ChannelType.Webhook;
+
+  /**
+   * Webhook provider
+   */
+  protected provider = new WebhookProvider();
+}

workers/webhook/src/provider.ts

@@ -0,0 +1,34 @@
+import NotificationsProvider from 'hawk-worker-sender/src/provider';
+import { Notification } from 'hawk-worker-sender/types/template-variables';
+import { toDelivery } from './templates';
+import WebhookDeliverer from './deliverer';
+
+/**
+ * Webhook notification provider.
+ * Supports all notification types via a single generic serializer —
+ * type comes from notification.type, payload is sanitized automatically.
+ */
+export default class WebhookProvider extends NotificationsProvider {
+  /**
+   * Class with the 'deliver' method for sending HTTP POST requests
+   */
+  private readonly deliverer: WebhookDeliverer;
+
+  constructor() {
+    super();
+
+    this.deliverer = new WebhookDeliverer();
+  }
+
+  /**
+   * Send webhook notification to recipient
+   *
+   * @param to - recipient endpoint URL
+   * @param notification - notification with payload and type
+   */
+  public async send(to: string, notification: Notification): Promise<void> {
+    const delivery = toDelivery(notification);
+
+    await this.deliverer.deliver(to, delivery);
+  }
+}