Add webhook notification channel to API layer (#626)

* Enhance notification system with webhook support

* Implement webhook validation for project and user notifications

* Update yarn.lock to include @hawk.so/types@0.5.9 and add webhook property to NotificationsChannelsDBScheme interface

* Refactor webhook endpoint validation by removing isPrivateIP function and related tests. Integrate private IP validation into ipValidator module for improved code organization.

* Refactor notification channel validation to use async functions for improved error handling. Update validation logic to await results from channel checks, enhancing overall reliability.

* Refactor webhook endpoint validation to utilize BLOCKED_HOSTNAMES and ALLOWED_PORTS constants from ipValidator module, improving code organization and maintainability.

* Refactor webhook validation logic in project and user notifications to remove endpoint checks when isEnabled is true, streamlining the validation process.

Author: Dobrunia

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hawk.api",
-  "version": "1.4.6",
+  "version": "1.4.7",
   "main": "index.ts",
   "license": "BUSL-1.1",
   "scripts": {
@@ -42,7 +42,7 @@
     "@graphql-tools/schema": "^8.5.1",
     "@graphql-tools/utils": "^8.9.0",
     "@hawk.so/nodejs": "^3.3.1",
-    "@hawk.so/types": "^0.5.8",
+    "@hawk.so/types": "^0.5.9",
     "@n1ru4l/json-patch-plus": "^0.2.0",
     "@node-saml/node-saml": "^5.0.1",
     "@octokit/oauth-methods": "^4.0.0",

src/rabbitmq.ts

@@ -28,6 +28,7 @@ export enum Queues {
   Telegram = 'notify/telegram',
   Slack = 'notify/slack',
   Loop = 'notify/loop',
+  Webhook = 'sender/webhook',
   Limiter = 'cron-tasks/limiter',
 }
 
@@ -90,6 +91,14 @@ export const WorkerPaths: Record<string, WorkerPath> = {
     queue: Queues.Loop,
   },
 
+  /**
+   * Path to webhook worker
+   */
+  Webhook: {
+    exchange: Exchanges.Empty,
+    queue: Queues.Webhook,
+  },
+
   /**
    * Path to limiter worker
    */

src/resolvers/projectNotifications.ts

@@ -5,6 +5,7 @@ import { ProjectNotificationsRuleDBScheme } from '@hawk.so/types';
 import { ResolverContextWithUser } from '../types/graphql';
 import { ApolloError, UserInputError } from 'apollo-server-express';
 import { NotificationsChannelsDBScheme } from '../types/notification-channels';
+import { validateWebhookEndpoint } from '../utils/webhookEndpointValidator';
 
 /**
  * Mutation payload for creating notifications rule from GraphQL Schema
@@ -101,7 +102,7 @@ function validateNotificationsRuleTresholdAndPeriod(
 /**
  * Return true if all passed channels are filled with correct endpoints
  */
-function validateNotificationsRuleChannels(channels: NotificationsChannelsDBScheme): string | null {
+async function validateNotificationsRuleChannels(channels: NotificationsChannelsDBScheme): Promise<string | null> {
   if (channels.email!.isEnabled) {
     if (!/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(channels.email!.endpoint)) {
       return 'Invalid email endpoint passed';
@@ -126,6 +127,14 @@ function validateNotificationsRuleChannels(channels: NotificationsChannelsDBSche
     }
   }
 
+  if (channels.webhook?.isEnabled) {
+    const webhookError = await validateWebhookEndpoint(channels.webhook.endpoint);
+
+    if (webhookError !== null) {
+      return webhookError;
+    }
+  }
+
   return null;
 }
 
@@ -152,7 +161,7 @@ export default {
         throw new ApolloError('No project with such id');
       }
 
-      const channelsValidationResult = validateNotificationsRuleChannels(input.channels);
+      const channelsValidationResult = await validateNotificationsRuleChannels(input.channels);
 
       if (channelsValidationResult !== null) {
         throw new UserInputError(channelsValidationResult);
@@ -190,7 +199,7 @@ export default {
         throw new ApolloError('No project with such id');
       }
 
-      const channelsValidationResult = validateNotificationsRuleChannels(input.channels);
+      const channelsValidationResult = await validateNotificationsRuleChannels(input.channels);
 
       if (channelsValidationResult !== null) {
         throw new UserInputError(channelsValidationResult);

src/resolvers/userNotifications.ts

@@ -2,6 +2,8 @@ import { ResolverContextWithUser } from '../types/graphql';
 import { UserNotificationsDBScheme, UserNotificationType } from '../models/user';
 import { NotificationsChannelsDBScheme } from '../types/notification-channels';
 import { UserDBScheme } from '@hawk.so/types';
+import { UserInputError } from 'apollo-server-express';
+import { validateWebhookEndpoint } from '../utils/webhookEndpointValidator';
 
 /**
  * We will get this structure from the client to update Channel settings
@@ -45,6 +47,14 @@ export default {
       { input }: ChangeUserNotificationsChannelPayload,
       { user, factories }: ResolverContextWithUser
     ): Promise<ChangeNotificationsResponse> {
+      if (input.webhook?.isEnabled) {
+        const webhookError = await validateWebhookEndpoint(input.webhook.endpoint);
+
+        if (webhookError !== null) {
+          throw new UserInputError(webhookError);
+        }
+      }
+
       const currentUser = await factories.usersFactory.findById(user.id);
       const currentNotifySet = currentUser?.notifications || {} as UserNotificationsDBScheme;
       const oldChannels = currentNotifySet.channels || {};

src/typeDefs/notifications.ts

@@ -49,6 +49,11 @@ export default gql`
     """
     loop: NotificationsChannelSettings
 
+    """
+    Webhook channel
+    """
+    webhook: NotificationsChannelSettings
+
     """
     Webpush
     """

src/typeDefs/notificationsInput.ts

@@ -45,6 +45,11 @@ export default gql`
     """
     loop: NotificationsChannelSettingsInput
 
+    """
+    Webhook channel
+    """
+    webhook: NotificationsChannelSettingsInput
+
     """
     Web push
     """

src/types/notification-channels.d.ts

@@ -36,6 +36,11 @@ export interface NotificationsChannelsDBScheme {
    * Pushes through the Hawk Desktop app
    */
   desktopPush?: NotificationsChannelSettingsDBScheme;
+
+  /**
+   * Alerts through a custom Webhook URL
+   */
+  webhook?: NotificationsChannelSettingsDBScheme;
 }
 
 /**

src/utils/ipValidator.ts

@@ -0,0 +1,64 @@
+/**
+ * Regex patterns matching private/reserved IP ranges:
+ *
+ * IPv4: 0.x (current-network), 10.x, 172.16-31.x, 192.168.x (RFC1918),
+ * 127.x (loopback), 169.254.x (link-local/metadata), 100.64-127.x (CGN/RFC6598),
+ * 255.255.255.255 (broadcast), 224-239.x (multicast),
+ * 192.0.2.x, 198.51.100.x, 203.0.113.x (documentation), 198.18-19.x (benchmarking).
+ *
+ * IPv6: ::1, ::, fe80 (link-local), fc/fd (ULA), ff (multicast).
+ *
+ * Also handles IPv4-mapped IPv6 (::ffff:A.B.C.D) and zone IDs (fe80::1%lo0).
+ */
+const PRIVATE_IP_PATTERNS: RegExp[] = [
+  /^0\./,
+  /^10\./,
+  /^127\./,
+  /^169\.254\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+  /^255\.255\.255\.255$/,
+  /^2(2[4-9]|3\d)\./,
+  /^192\.0\.2\./,
+  /^198\.51\.100\./,
+  /^203\.0\.113\./,
+  /^198\.1[89]\./,
+  /^::1$/,
+  /^::$/,
+  /^fe80/i,
+  /^f[cd]/i,
+  /^ff[0-9a-f]{2}:/i,
+  /^::ffff:(0\.|10\.|127\.|169\.254\.|172\.(1[6-9]|2\d|3[01])\.|192\.168\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/i,
+];
+
+/**
+ * Checks whether an IP address belongs to a private/reserved range.
+ * Strips zone ID before matching (e.g. fe80::1%lo0).
+ *
+ * @param ip - IP address string (v4 or v6)
+ */
+export function isPrivateIP(ip: string): boolean {
+  const bare = ip.split('%')[0];
+
+  return PRIVATE_IP_PATTERNS.some((pattern) => pattern.test(bare));
+}
+
+/**
+ * Hostnames blocked regardless of DNS resolution
+ */
+export const BLOCKED_HOSTNAMES: RegExp[] = [
+  /^localhost$/i,
+  /\.local$/i,
+  /\.internal$/i,
+  /\.lan$/i,
+  /\.localdomain$/i,
+];
+
+/**
+ * Only these ports are allowed for webhook delivery
+ */
+export const ALLOWED_PORTS: Record<string, number> = {
+  'http:': 80,
+  'https:': 443,
+};

src/utils/personalNotifications.ts

@@ -52,4 +52,14 @@ export default async function sendNotification(user: UserDBScheme, task: SenderW
       },
     });
   }
+
+  if (user.notifications.channels.webhook?.isEnabled) {
+    await enqueue(WorkerPaths.Webhook, {
+      type: task.type,
+      payload: {
+        ...task.payload,
+        endpoint: user.notifications.channels.webhook.endpoint,
+      },
+    });
+  }
 }

src/utils/webhookEndpointValidator.ts

@@ -0,0 +1,59 @@
+import dns from 'dns';
+import { isPrivateIP, BLOCKED_HOSTNAMES, ALLOWED_PORTS } from './ipValidator';
+
+/**
+ * Validates a webhook endpoint URL for SSRF safety.
+ * Returns null if valid, or an error message string if invalid.
+ *
+ * Checks:
+ * - Protocol whitelist (http/https)
+ * - Port whitelist (80/443)
+ * - Hostname blocklist (localhost, *.local, etc.)
+ * - Private IP in URL
+ * - DNS resolution — all A/AAAA records must be public
+ *
+ * @param endpoint - webhook URL to validate
+ */
+export async function validateWebhookEndpoint(endpoint: string): Promise<string | null> {
+  let url: URL;
+
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return 'Invalid webhook URL';
+  }
+
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return 'Webhook URL must use http or https protocol';
+  }
+
+  const requestedPort = url.port ? Number(url.port) : ALLOWED_PORTS[url.protocol];
+
+  if (requestedPort !== ALLOWED_PORTS[url.protocol]) {
+    return `Webhook URL port ${requestedPort} is not allowed — only 80 (http) and 443 (https)`;
+  }
+
+  const hostname = url.hostname;
+
+  if (BLOCKED_HOSTNAMES.some((pattern) => pattern.test(hostname))) {
+    return `Webhook hostname "${hostname}" is not allowed`;
+  }
+
+  if (isPrivateIP(hostname)) {
+    return 'Webhook URL points to a private/reserved IP address';
+  }
+
+  try {
+    const results = await dns.promises.lookup(hostname, { all: true });
+
+    for (const { address } of results) {
+      if (isPrivateIP(address)) {
+        return `Webhook hostname resolves to a private IP address (${address})`;
+      }
+    }
+  } catch {
+    return `Cannot resolve webhook hostname "${hostname}"`;
+  }
+
+  return null;
+}