fix: a

Author: scopsy

apps/api/src/app/shared/framework/swagger/swagger.controller.ts

@@ -11,6 +11,8 @@ import {
 } from './open.api.manipulation.component';
 import metadata from '../../../../metadata';
 import { API_KEY_SWAGGER_SECURITY_NAME, BEARER_SWAGGER_SECURITY_NAME } from '@novu/application-generic';
+import { webhookEvents } from '../../../webhooks/webhooks.const';
+import { WorkflowResponseDto } from '../../../workflows-v2/dtos/workflow-response.dto';
 
 export const API_KEY_SECURITY_DEFINITIONS: SecuritySchemeObject = {
   type: 'apiKey',
@@ -45,7 +47,7 @@ function buildBaseOptions() {
     )
     .addTag(
       'Subscribers',
-      `A subscriber in Novu represents someone who should receive a message. A subscriber’s profile information contains important attributes about the subscriber that will be used in messages (name, email). The subscriber object can contain other key-value pairs that can be used to further personalize your messages.`,
+      `A subscriber in Novu represents someone who should receive a message. A subscriber's profile information contains important attributes about the subscriber that will be used in messages (name, email). The subscriber object can contain other key-value pairs that can be used to further personalize your messages.`,
       { url: 'https://docs.novu.co/subscribers/subscribers' }
     )
     .addTag(
@@ -63,6 +65,7 @@ function buildBaseOptions() {
     //   `All notifications are sent via a workflow. Each workflow acts as a container for the logic and blueprint that are associated with a type of notification in your system.`,
     //   { url: 'https://docs.novu.co/workflows' }
     // )
+
     .addTag(
       'Messages',
       `A message in Novu represents a notification delivered to a recipient on a particular channel. Messages contain information about the request that triggered its delivery, a view of the data sent to the recipient, and a timeline of its lifecycle events. Learn more about messages.`,
@@ -82,13 +85,17 @@ function buildOpenApiBaseDocument(internalSdkGeneration: boolean | undefined) {
 }
 
 function buildFullDocumentWithPath(app: INestApplication<any>, baseDocument: Omit<OpenAPIObject, 'paths'>) {
+  // Define extraModels to ensure webhook payload DTOs are included in the schema definitions
+  // Add other relevant payload DTOs here if more webhooks are defined
+  const allWebhookPayloadDtos = [...new Set(webhookEvents.map((event) => event.payloadDto))];
+
   const document = injectDocumentComponents(
     SwaggerModule.createDocument(app, baseDocument, {
       operationIdFactory: (controllerKey: string, methodKey: string) => `${controllerKey}_${methodKey}`,
       deepScanRoutes: true,
       ignoreGlobalPrefix: false,
       include: [],
-      extraModels: [],
+      extraModels: [...allWebhookPayloadDtos], // Make sure payload DTOs are processed
     })
   );
   return document;
@@ -112,12 +119,84 @@ function publishLegacyOpenApiDoc(app: INestApplication<any>, document: OpenAPIOb
   });
 }
 
+/**
+ * Generates the `x-webhooks` section for the OpenAPI document based on defined events and DTOs.
+ * Follows the OpenAPI specification for webhooks: https://spec.openapis.org/oas/v3.1.0#fixed-fields-1:~:text=Webhooks%20Object
+ */
+function generateWebhookDefinitions(document: OpenAPIObject) {
+  const webhooksDefinition: Record<string, any> = {}; // Structure matches Path Item Object
+
+  webhookEvents.forEach((webhook) => {
+    // Assume the schema name matches the DTO class name (generated by Swagger)
+    const payloadSchemaRef = `#/components/schemas/${webhook.payloadDto.name}`;
+    const wrapperSchemaName = `${webhook.payloadDto.name}WebhookPayloadWrapper`; // Unique name for the wrapper schema
+
+    // Define the wrapper schema in components/schemas if it doesn't exist
+    if (document.components && !document.components.schemas?.[wrapperSchemaName]) {
+      if (!document.components.schemas) {
+        document.components.schemas = {};
+      }
+      document.components.schemas[wrapperSchemaName] = {
+        type: 'object',
+        properties: {
+          type: { type: 'string', enum: [webhook.event], description: 'The type of the webhook event.' },
+          data: {
+            description: 'The actual event data payload.',
+            allOf: [{ $ref: payloadSchemaRef }], // Use allOf to correctly reference the payload schema
+          },
+          timestamp: { type: 'string', format: 'date-time', description: 'ISO timestamp of when the event occurred.' },
+          environmentId: { type: 'string', description: 'The ID of the environment associated with the event.' },
+          object: {
+            type: 'string',
+            enum: [webhook.objectType],
+            description: 'The type of object the event relates to.',
+          },
+        },
+        required: ['type', 'data', 'timestamp', 'environmentId', 'object'],
+      };
+    }
+
+    webhooksDefinition[webhook.event] = {
+      // This structure represents a Path Item Object, describing the webhook POST request.
+      post: {
+        summary: `Event: ${webhook.event}`,
+        description: `This webhook is triggered when a \`${webhook.objectType}\` event (\`${
+          webhook.event
+        }\`) occurs. The payload contains the details of the event. Configure your webhook endpoint URL in the Novu dashboard.`,
+        requestBody: {
+          description: `Webhook payload for the \`${webhook.event}\` event.`,
+          required: true,
+          content: {
+            'application/json': {
+              schema: { $ref: `#/components/schemas/${wrapperSchemaName}` }, // Reference the wrapper schema
+            },
+          },
+        },
+        responses: {
+          '200': {
+            description: 'Acknowledges successful receipt of the webhook. No response body is expected.',
+          },
+          // Consider adding other responses (e.g., 4xx for signature validation failure, 5xx for processing errors)
+        },
+        tags: ['Webhooks'], // Assign to a 'Webhooks' tag
+      },
+    };
+  });
+
+  document['x-webhooks'] = webhooksDefinition;
+}
+
 export const setupSwagger = async (app: INestApplication, internalSdkGeneration?: boolean) => {
   await SwaggerModule.loadPluginMetadata(metadata);
   const baseDocument = buildOpenApiBaseDocument(internalSdkGeneration);
   const document = buildFullDocumentWithPath(app, baseDocument);
+
+  // Generate and add x-webhooks section FIRST
+  generateWebhookDefinitions(document);
+
   publishDeprecatedDocument(app, document);
   publishLegacyOpenApiDoc(app, document);
+
   return publishSdkSpecificDocumentAndReturnDocument(app, document, internalSdkGeneration);
 };
 

apps/api/src/app/webhooks/webhooks.const.ts

@@ -0,0 +1,21 @@
+import { WebhookEventEnum, WebhookObjectTypeEnum } from './dtos/webhook-payload.dto';
+import { WorkflowResponseDto } from '../workflows-v2/dtos/workflow-response.dto';
+
+export const webhookEvents = [
+  {
+    event: WebhookEventEnum.WORKFLOW_UPDATED,
+    payloadDto: WorkflowResponseDto,
+    objectType: WebhookObjectTypeEnum.WORKFLOW,
+  },
+  {
+    event: WebhookEventEnum.WORKFLOW_CREATED,
+    payloadDto: WorkflowResponseDto,
+    objectType: WebhookObjectTypeEnum.WORKFLOW,
+  },
+  {
+    event: WebhookEventEnum.WORKFLOW_DELETED,
+    payloadDto: WorkflowResponseDto,
+    objectType: WebhookObjectTypeEnum.WORKFLOW,
+  },
+  // Add other webhook events here as needed
+];