feat(webhook): unify webhook delivery structure and remove deprecated templates

Author: Dobrunia

workers/webhook/src/deliverer.ts

@@ -1,6 +1,7 @@
 import https from 'https';
 import http from 'http';
 import { createLogger, format, Logger, transports } from 'winston';
+import { WebhookDelivery } from '../types/template';
 
 /**
  * Timeout for webhook delivery in milliseconds
@@ -35,13 +36,14 @@ export default class WebhookDeliverer {
   });
 
   /**
-   * Sends JSON payload to the webhook endpoint via HTTP POST
+   * 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 payload - JSON body to send
+   * @param delivery - webhook delivery { type, payload }
    */
-  public async deliver(endpoint: string, payload: Record<string, unknown>): Promise<void> {
-    const body = JSON.stringify(payload);
+  public async deliver(endpoint: string, delivery: WebhookDelivery): Promise<void> {
+    const body = JSON.stringify(delivery);
     const url = new URL(endpoint);
     const transport = url.protocol === 'https:' ? https : http;
 
@@ -53,6 +55,7 @@ export default class WebhookDeliverer {
           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,

workers/webhook/src/provider.ts

@@ -1,11 +1,12 @@
 import NotificationsProvider from 'hawk-worker-sender/src/provider';
-import { Notification, EventsTemplateVariables } from 'hawk-worker-sender/types/template-variables';
-import templates from './templates';
-import { WebhookTemplate } from '../types/template';
+import { Notification } from 'hawk-worker-sender/types/template-variables';
+import { toDelivery } from './templates';
 import WebhookDeliverer from './deliverer';
 
 /**
- * This class provides a 'send' method that renders and sends a webhook notification
+ * 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 {
   /**
@@ -26,16 +27,8 @@ export default class WebhookProvider extends NotificationsProvider {
    * @param notification - notification with payload and type
    */
   public async send(to: string, notification: Notification): Promise<void> {
-    let template: WebhookTemplate;
+    const delivery = toDelivery(notification);
 
-    switch (notification.type) {
-      case 'event': template = templates.EventTpl; break;
-      case 'several-events': template = templates.SeveralEventsTpl; break;
-      default: return;
-    }
-
-    const payload = template(notification.payload as EventsTemplateVariables);
-
-    await this.deliverer.deliver(to, payload);
+    await this.deliverer.deliver(to, delivery);
   }
 }

workers/webhook/src/templates/event.ts

@@ -0,0 +1,55 @@
+import { Notification } from 'hawk-worker-sender/types/template-variables';
+import { WebhookDelivery } from '../../types/template';
+
+/**
+ * List of internal fields that should not be exposed in webhook payload
+ */
+const INTERNAL_FIELDS = new Set(['host', 'hostOfStatic']);
+
+/**
+ * Recursively converts MongoDB ObjectIds and other non-JSON-safe values to strings
+ *
+ * @param value - any value to sanitize
+ */
+function sanitize(value: unknown): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  if (typeof value === 'object' && '_bsontype' in (value as Record<string, unknown>)) {
+    return String(value);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(sanitize);
+  }
+
+  if (typeof value === 'object') {
+    const result: Record<string, unknown> = {};
+
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (!INTERNAL_FIELDS.has(k)) {
+        result[k] = sanitize(v);
+      }
+    }
+
+    return result;
+  }
+
+  return value;
+}
+
+/**
+ * Generic webhook template — handles any notification type
+ * by passing through the sanitized payload as-is.
+ *
+ * Used as a fallback when no curated template exists for the notification type.
+ *
+ * @param notification - notification with type and payload
+ */
+export default function render(notification: Notification): WebhookDelivery {
+  return {
+    type: notification.type,
+    payload: sanitize(notification.payload) as Record<string, unknown>,
+  };
+}

workers/webhook/src/templates/generic.ts

@@ -1,7 +1 @@
-import EventTpl from './event';
-import SeveralEventsTpl from './several-events';
-
-export default {
-  EventTpl,
-  SeveralEventsTpl,
-};
+export { default as toDelivery } from './generic';

workers/webhook/src/templates/index.ts

@@ -0,0 +1,33 @@
+import { AssigneeNotification } from 'hawk-worker-sender/types/template-variables';
+import { ObjectId } from 'mongodb';
+
+/**
+ * Example of assignee notify template variables
+ */
+export default {
+  type: 'assignee',
+  payload: {
+    host: process.env.GARAGE_URL,
+    hostOfStatic: process.env.API_STATIC_URL,
+    project: {
+      _id: new ObjectId('5d206f7f9aaf7c0071d64596'),
+      token: 'project-token',
+      name: 'Project',
+      workspaceId: new ObjectId('5d206f7f9aaf7c0071d64596'),
+      uidAdded: new ObjectId('5d206f7f9aaf7c0071d64596'),
+      notifications: [],
+    },
+    event: {
+      totalCount: 5,
+      groupHash: 'abc123',
+      payload: {
+        title: 'TypeError: Cannot read property',
+      },
+    },
+    whoAssigned: {
+      name: 'John Doe',
+      email: 'john@example.com',
+    },
+    daysRepeated: 3,
+  },
+} as AssigneeNotification;

workers/webhook/src/templates/several-events.ts

@@ -1,6 +1,6 @@
-import templates from '../src/templates';
 import EventNotifyMock from './__mocks__/event-notify';
 import SeveralEventsNotifyMock from './__mocks__/several-events-notify';
+import AssigneeNotifyMock from './__mocks__/assignee-notify';
 import WebhookProvider from '../src/provider';
 
 /**
@@ -18,9 +18,6 @@ const deliver = jest.fn();
  */
 jest.mock('./../src/deliverer.ts', () => {
   return jest.fn().mockImplementation(() => {
-    /**
-     * Now we can track calls to 'deliver'
-     */
     return {
       deliver: deliver,
     };
@@ -35,48 +32,92 @@ afterEach(() => {
 });
 
 describe('WebhookProvider', () => {
-  /**
-   * Check that the 'send' method works without errors
-   */
-  it('The "send" method should render and deliver message', async () => {
+  it('should deliver a message with { type, payload } structure', async () => {
     const provider = new WebhookProvider();
 
     await provider.send(webhookEndpointSample, EventNotifyMock);
 
     expect(deliver).toHaveBeenCalledTimes(1);
-    expect(deliver).toHaveBeenCalledWith(webhookEndpointSample, expect.anything());
+    expect(deliver).toHaveBeenCalledWith(webhookEndpointSample, expect.objectContaining({
+      type: 'event',
+      payload: expect.any(Object),
+    }));
   });
 
-  /**
-   * Logic for select the template depended on events count
-   */
-  describe('Select correct template', () => {
-    /**
-     * If there is a single event in payload, use the 'event' template
-     */
-    it('Select the event template if there is a single event in notify payload', async () => {
-      const provider = new WebhookProvider();
-      const EventTpl = jest.spyOn(templates, 'EventTpl');
-      const SeveralEventsTpl = jest.spyOn(templates, 'SeveralEventsTpl');
-
-      await provider.send(webhookEndpointSample, EventNotifyMock);
-
-      expect(EventTpl).toHaveBeenCalledTimes(1);
-      expect(SeveralEventsTpl).toHaveBeenCalledTimes(0);
-    });
-
-    /**
-     * If there are several events in payload, use the 'several-events' template
-     */
-    it('Select the several-events template if there are several events in notify payload', async () => {
-      const provider = new WebhookProvider();
-      const EventTpl = jest.spyOn(templates, 'EventTpl');
-      const SeveralEventsTpl = jest.spyOn(templates, 'SeveralEventsTpl');
-
-      await provider.send(webhookEndpointSample, SeveralEventsNotifyMock);
-
-      expect(EventTpl).toHaveBeenCalledTimes(0);
-      expect(SeveralEventsTpl).toHaveBeenCalledTimes(1);
-    });
+  it('should preserve notification type in delivery', async () => {
+    const provider = new WebhookProvider();
+
+    await provider.send(webhookEndpointSample, EventNotifyMock);
+    expect(deliver.mock.calls[0][1].type).toBe('event');
+
+    deliver.mockClear();
+
+    await provider.send(webhookEndpointSample, SeveralEventsNotifyMock);
+    expect(deliver.mock.calls[0][1].type).toBe('several-events');
+
+    deliver.mockClear();
+
+    await provider.send(webhookEndpointSample, AssigneeNotifyMock);
+    expect(deliver.mock.calls[0][1].type).toBe('assignee');
+  });
+
+  it('should strip internal fields (host, hostOfStatic) from payload', async () => {
+    const provider = new WebhookProvider();
+
+    await provider.send(webhookEndpointSample, {
+      type: 'payment-failed',
+      payload: {
+        host: 'https://garage.hawk.so',
+        hostOfStatic: 'https://api.hawk.so',
+        workspace: { name: 'Workspace' },
+        reason: 'Insufficient funds',
+      },
+    } as any);
+
+    const delivery = deliver.mock.calls[0][1];
+
+    expect(delivery.payload).not.toHaveProperty('host');
+    expect(delivery.payload).not.toHaveProperty('hostOfStatic');
+    expect(delivery.payload).toHaveProperty('reason', 'Insufficient funds');
+  });
+
+  it('should handle all known notification types without throwing', async () => {
+    const provider = new WebhookProvider();
+
+    const types = [
+      'event',
+      'several-events',
+      'assignee',
+      'block-workspace',
+      'blocked-workspace-reminder',
+      'payment-failed',
+      'payment-success',
+      'days-limit-almost-reached',
+      'events-limit-almost-reached',
+      'sign-up',
+      'password-reset',
+      'workspace-invite',
+    ];
+
+    for (const type of types) {
+      await expect(
+        provider.send(webhookEndpointSample, {
+          type,
+          payload: { host: 'h', hostOfStatic: 's' },
+        } as any)
+      ).resolves.toBeUndefined();
+    }
+
+    expect(deliver).toHaveBeenCalledTimes(types.length);
+  });
+
+  it('should only have { type, payload } keys at root level', async () => {
+    const provider = new WebhookProvider();
+
+    await provider.send(webhookEndpointSample, EventNotifyMock);
+
+    const delivery = deliver.mock.calls[0][1];
+
+    expect(Object.keys(delivery).sort()).toEqual(['payload', 'type']);
   });
 });