fix(openapi): propagate webhook responses from OpenAPI to IR

packages/cli/api-importers/openapi-to-ir/src/3.1/paths/operations/WebhookConverter.ts

@@ -1,4 +1,4 @@
-import { V2WebhookExample, Webhook, WebhookPayload } from "@fern-api/ir-sdk";
+import { V2WebhookExample, Webhook, WebhookPayload, WebhookResponse } from "@fern-api/ir-sdk";
 
 import { AbstractOperationConverter } from "./AbstractOperationConverter";
 
@@ -75,6 +75,8 @@ export class WebhookConverter extends AbstractOperationConverter {
             return undefined;
         }
 
+        const responses = this.convertWebhookResponses();
+
         return {
             audiences:
                 this.context.getAudiences({
@@ -89,6 +91,7 @@ export class WebhookConverter extends AbstractOperationConverter {
                 method: httpMethod,
                 headers,
                 payload,
+                responses: responses.length > 0 ? responses : undefined,
                 examples: [],
                 availability: this.context.getAvailability({
                     node: this.operation,
@@ -108,6 +111,33 @@ export class WebhookConverter extends AbstractOperationConverter {
         };
     }
 
+    private convertWebhookResponses(): WebhookResponse[] {
+        const responses: WebhookResponse[] = [];
+
+        if (this.operation.responses == null) {
+            return responses;
+        }
+
+        for (const [statusCode, response] of Object.entries(this.operation.responses)) {
+            const statusCodeNum = parseInt(statusCode);
+            if (isNaN(statusCodeNum)) {
+                continue;
+            }
+
+            const resolvedResponse = this.context.resolveMaybeReference({
+                schemaOrReference: response,
+                breadcrumbs: [...this.breadcrumbs, "responses", statusCode]
+            });
+
+            responses.push({
+                statusCode: statusCodeNum,
+                docs: resolvedResponse?.description
+            });
+        }
+
+        return responses;
+    }
+
     private getWebhookV2ExamplesFromRequestBodyV2Examples(
         requestBodyV2Examples: Record<string, unknown>
     ): Record<string, V2WebhookExample> {

packages/cli/api-importers/v3-importer-tests/src/__test__/__snapshots__/v3-sdks/webhooks.json

@@ -238,6 +238,12 @@
           },
           "type": "reference"
         },
+        "responses": [
+          {
+            "statusCode": 200,
+            "docs": "Return a 200 status to indicate that the data was received successfully"
+          }
+        ],
         "examples": [],
         "v2Examples": {
           "autogeneratedExamples": {},

packages/cli/cli/versions.yml

@@ -1,4 +1,12 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
+- changelogEntry:
+    - summary: |
+        Propagate webhook responses (e.g., 204, 400, 500 status codes) from OpenAPI specs to the IR. Webhook endpoints can now define expected response status codes and descriptions, which are captured in the IR for use by generators and documentation.
+      type: feat
+  irVersion: 63
+  createdAt: "2025-12-10"
+  version: 3.7.0
+
 - changelogEntry:
     - summary: |
         Validate examples in `fern check` against OpenAPI schemas.

packages/cli/ete-tests/src/tests/ir/__snapshots__/ir.test.ts.snap

@@ -43383,6 +43383,7 @@ exports[`ir > {"name":"webhooks"} 1`] = `
                         }
                     ]
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,

packages/cli/generation/ir-generator-tests/src/ir/__test__/irs/audiences.json

@@ -1387,6 +1387,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,

packages/cli/generation/ir-generator-tests/src/ir/__test__/irs/environmentAudiences.json

@@ -5175,6 +5175,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,
@@ -5277,6 +5278,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,

packages/cli/generation/ir-generator-tests/src/ir/__test__/irs/environmentAudiencesAllHack.json

@@ -4016,6 +4016,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,
@@ -4118,6 +4119,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,

packages/cli/generation/ir-generator-tests/src/ir/__test__/irs/environmentAudiencesSelectHack.json

@@ -1411,6 +1411,7 @@
                     },
                     "docs": null
                 },
+                "responses": null,
                 "examples": null,
                 "v2Examples": null,
                 "availability": null,

packages/cli/generation/ir-generator/src/converters/convertWebhookGroup.ts

@@ -49,6 +49,7 @@ export function convertWebhookGroup({
                       )
                     : [],
             payload: convertWebhookPayloadSchema({ payload: webhook.payload, file }),
+            responses: undefined,
             examples:
                 webhook.examples != null
                     ? convertWebhookExamples({

packages/cli/generation/ir-migrations/src/migrations/v63-to-v62/migrateFromV63ToV62.ts

@@ -49,7 +49,8 @@ export const V63_TO_V62_MIGRATION: IrMigration<
     migrateBackwards: (v63: IntermediateRepresentation): IrVersions.V62.ir.IntermediateRepresentation => {
         return {
             ...v63,
-            errors: stripHeadersFromErrors(v63.errors)
+            errors: stripHeadersFromErrors(v63.errors),
+            webhookGroups: stripResponsesFromWebhooks(v63.webhookGroups)
         };
     }
 };
@@ -66,3 +67,18 @@ function stripHeadersFromErrors(
 
     return result;
 }
+
+function stripResponsesFromWebhooks(
+    webhookGroups: IntermediateRepresentation["webhookGroups"]
+): Record<string, IrVersions.V62.webhooks.WebhookGroup> {
+    const result: Record<string, IrVersions.V62.webhooks.WebhookGroup> = {};
+
+    for (const [groupId, webhookGroup] of Object.entries(webhookGroups)) {
+        result[groupId] = webhookGroup.map((webhook) => {
+            const { responses, ...v62Webhook } = webhook;
+            return v62Webhook as IrVersions.V62.webhooks.Webhook;
+        });
+    }
+
+    return result;
+}

packages/cli/register/src/ir-to-fdr-converter/__test__/__snapshots__/webhook-openapi-responses-ir.snap

@@ -1193,6 +1193,20 @@
           },
           "type": "reference",
         },
+        "responses": [
+          {
+            "docs": "Webhook received successfully (HTTP 204 No Content)",
+            "statusCode": 204,
+          },
+          {
+            "docs": "Invalid payload or authentication failure",
+            "statusCode": 400,
+          },
+          {
+            "docs": "Server error processing webhook",
+            "statusCode": 500,
+          },
+        ],
         "v2Examples": {
           "autogeneratedExamples": {
             "paymentSessionsPaymentSessionCompletedWebhookExample": {

packages/ir-sdk/fern/apis/ir-types-latest/definition/webhooks.yml

@@ -16,9 +16,18 @@ types:
       method: WebhookHttpMethod
       headers: list<http.HttpHeader>
       payload: WebhookPayload
+      responses: optional<list<WebhookResponse>>
       examples: optional<list<ExampleWebhookCall>>
       v2Examples: optional<examples.V2WebhookExamples>
 
+  WebhookResponse:
+    docs: |
+      A response that a webhook endpoint can return.
+      Typically used to indicate success (2xx), client errors (4xx), or server errors (5xx).
+    extends: commons.WithDocs
+    properties:
+      statusCode: integer
+
   WebhookName: commons.Name
 
   WebhookPayload: