Add live example to webhook-payload-snippet and align with endpoint-schema-snippet

fern/apis/fai/openapi.json

@@ -4423,7 +4423,7 @@
               }
             ],
             "title": "Previous Version",
-            "description": "The current published version before this change, e.g. '1.2.3'. Provided for context only — not included in the commit message.",
+            "description": "The current published version before this change, e.g. '1.2.3'. Provided for context only \u2014 not included in the commit message.",
             "default": null
           },
           "prior_changelog": {
@@ -7578,5 +7578,76 @@
       "url": "http://localhost:8080",
       "x-fern-server-name": "Local"
     }
-  ]
-}
+  ],
+  "webhooks": {
+    "conversation-completed": {
+      "post": {
+        "operationId": "on-conversation-completed",
+        "summary": "Conversation completed",
+        "description": "Sent when an Ask Fern conversation finishes. Use this to log analytics, sync transcripts, or trigger follow-up workflows.",
+        "tags": [
+          "Scribe webhooks"
+        ],
+        "x-fern-audiences": [
+          "customers"
+        ],
+        "requestBody": {
+          "description": "Payload describing the completed conversation.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "event": {
+                    "type": "string",
+                    "description": "The type of event.",
+                    "example": "conversation.completed"
+                  },
+                  "conversationId": {
+                    "type": "string",
+                    "description": "Unique identifier for the conversation.",
+                    "example": "conv_01HMT8X9PZ4QY6F7A2B3C4D5E6"
+                  },
+                  "domain": {
+                    "type": "string",
+                    "description": "The domain the conversation took place on.",
+                    "example": "buildwithfern.com"
+                  },
+                  "messageCount": {
+                    "type": "integer",
+                    "description": "Total number of messages exchanged.",
+                    "example": 6
+                  },
+                  "completedAt": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "Timestamp when the conversation completed.",
+                    "example": "2026-05-11T14:23:07.000Z"
+                  }
+                },
+                "required": [
+                  "event",
+                  "conversationId",
+                  "domain",
+                  "completedAt"
+                ],
+                "example": {
+                  "event": "conversation.completed",
+                  "conversationId": "conv_01HMT8X9PZ4QY6F7A2B3C4D5E6",
+                  "domain": "buildwithfern.com",
+                  "messageCount": 6,
+                  "completedAt": "2026-05-11T14:23:07.000Z"
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Return a 2xx status to acknowledge receipt."
+          }
+        }
+      }
+    }
+  }
+}

fern/products/docs/docs.yml

@@ -509,6 +509,8 @@ navigation:
           hidden: true
       - website:
           hidden: true
+      - scribeWebhooks:
+          hidden: true
     # must be included to use the schema component
   - api: API reference
     api-name: docs-yml

fern/products/docs/pages/component-library/default-components/webhook-payload-snippet.mdx

@@ -4,16 +4,26 @@ description: Reference a webhook payload from your API Reference to display exam
 ---
 
 
-Use the `<WebhookPayloadSnippet>` component to reference a webhook payload from your API Reference.
+The `<WebhookPayloadSnippet>` component displays a webhook's request payload schema from your API Reference. It renders the same fields, types, and example values that appear on the webhook's full API Reference page, so readers can inspect the payload inline alongside your prose.
+
+To display the schema for a regular HTTP endpoint, use the [`<EndpointSchemaSnippet>`](/learn/docs/writing-content/components/endpoint-schema-snippet) component.
 
 ## Usage
 
+Reference a webhook by its `operationId`.
+
+<div className="highlight-frame">
+  <div className="highlight-frame-content">
+  <WebhookPayloadSnippet webhook="on-conversation-completed" />
+  </div>
+</div>
+
 ```jsx Markdown
-<WebhookPayloadSnippet webhook="on-order-created" />
+<WebhookPayloadSnippet webhook="on-conversation-completed" />
 ```
 
 ## Properties
 
 <ParamField path="webhook" type="string" required={true}>
-  The operation ID of the webhook to display.
+  The `operationId` of the webhook to display. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `payments::on-payment-succeeded`).
 </ParamField>