feat(docs): add WebhookPayloadSnippet component for embedding webhook payload examples (#6105)

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Catherine Deskur <[email protected]>
Co-authored-by: Catherine Deskur <[email protected]>

Author: devin-ai-integration[bot]

packages/commons/docs-loader/src/editable-docs-loader.ts

@@ -37,6 +37,8 @@ class EditableDocsLoader implements DocsLoader {
     getEndpointByLocator = (method: HttpMethod, path: string, example?: string) =>
         this.readOnlyDocsLoader.getEndpointByLocator(method, path, example);
 
+    getWebhookByLocator = (webhookId: string) => this.readOnlyDocsLoader.getWebhookByLocator(webhookId);
+
     getRoot = () => this.readOnlyDocsLoader.getRoot();
 
     getNavigationNode = (id: string) => this.readOnlyDocsLoader.getNavigationNode(id);

packages/commons/docs-loader/src/prefetched-docs-loader.ts

@@ -140,6 +140,16 @@ export class PrefetchedDocsLoader implements DocsLoader<false> {
         return this.notSupported("getEndpointByLocator");
     }
 
+    getWebhookByLocator(_webhookId: string):
+        | {
+              apiDefinitionId: ApiDefinition.ApiDefinitionId;
+              webhook: ApiDefinition.WebhookDefinition;
+              slug: Slug | undefined;
+          }
+        | undefined {
+        return this.notSupported("getWebhookByLocator");
+    }
+
     getRoot(): FernNavigation.RootNode {
         return this.notSupported("getRoot");
     }

packages/commons/docs-loader/src/readonly-docs-loader.ts

@@ -7,6 +7,7 @@ import {
     type DynamicIRsByLanguage,
     type FernFonts,
     findEndpoint,
+    findWebhook,
     generateFernColorPalette,
     generateFonts,
     getDocsUrlMetadata,
@@ -631,6 +632,52 @@ const getEndpointByLocator = async (
     notFound();
 };
 
+const getWebhookByLocator = async (
+    domainKey: string,
+    webhookId: string
+): Promise<
+    | {
+          apiDefinitionId: ApiDefinition.ApiDefinitionId;
+          webhook: ApiDefinition.WebhookDefinition;
+          slug: Slug | undefined;
+      }
+    | undefined
+> => {
+    const root = await unsafe_getFullRoot(domainKey);
+
+    const apiIds = new Set<string>();
+    FernNavigation.traverseBF(root, (node) => {
+        if (FernNavigation.hasMetadata(node) && "apiDefinitionId" in node && node.apiDefinitionId) {
+            apiIds.add(node.apiDefinitionId);
+        }
+        return CONTINUE;
+    });
+
+    for (const apiId of apiIds) {
+        const api = await getApi(domainKey, apiId);
+        const webhook = findWebhook({
+            apiDefinition: api,
+            webhookId
+        });
+        if (webhook != null) {
+            const webhookNode = FernNavigation.NodeCollector.collect(root)
+                .getNodesInOrder()
+                .filter(FernNavigation.hasMetadata)
+                .find(
+                    (node) =>
+                        node.type === "webhook" && node.apiDefinitionId === api.id && node.webhookId === webhook.id
+                );
+            return {
+                apiDefinitionId: api.id,
+                webhook,
+                slug: webhookNode?.slug
+            };
+        }
+    }
+    console.error(`Could not find webhook ${webhookId}`);
+    return undefined;
+};
+
 export function convertResponseToRootNode(response: DocsV2Read.LoadDocsForUrlResponse, edgeFlags: EdgeFlags) {
     let root: FernNavigation.RootNode | undefined;
     if (response.definition.config.root) {
@@ -1434,6 +1481,13 @@ const createCachedDocsLoaderImpl = async (
                 { tags: [domainKey, "endpointByLocator"] }
             )
         ),
+        getWebhookByLocator: cache(
+            unstable_cache(
+                (webhookId: string) => getWebhookByLocator(domainKey, webhookId),
+                [domainKey, config.cacheKeySuffix],
+                { tags: [domainKey, "webhookByLocator"] }
+            )
+        ),
         getRoot: async () => {
             return getRootCached(config)(domainKey, await getAuthState(), await authConfig);
         },

packages/commons/docs-server/src/docs-loader.ts

@@ -104,6 +104,19 @@ export interface DocsLoader<IsAsync extends boolean = true> {
         IsAsync
     >;
 
+    /**
+     * @returns the webhook definition for the given webhook locator (ID or path), or undefined if not found
+     */
+    getWebhookByLocator: (webhookId: string) => MaybePromise<
+        | {
+              apiDefinitionId: ApiDefinition.ApiDefinitionId;
+              webhook: ApiDefinition.WebhookDefinition;
+              slug: Slug | undefined;
+          }
+        | undefined,
+        IsAsync
+    >;
+
     /**
      * @returns the root node of the docs (aware of authentication)
      */

packages/commons/docs-server/src/processRequestSnippetComponents.ts

@@ -62,3 +62,76 @@ export function getMatchablePermutationsForEndpoint(
     });
     return possiblePaths;
 }
+
+/**
+ * Converts a camelCase string to kebab-case.
+ * e.g., "onOrderCreated" -> "on-order-created"
+ */
+function camelToKebab(str: string): string {
+    return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * Find a webhook by its ID, operationId, or path.
+ * Webhooks can be identified by:
+ * - Exact ID (e.g., "subpackage_orders.onOrderCreated")
+ * - Operation ID (e.g., "on-order-created")
+ * - ID suffix after the last dot (e.g., "onOrderCreated")
+ * - camelCase converted to kebab-case for operationId matching (e.g., "onOrderCreated" -> "on-order-created")
+ * - Path (e.g., "/webhooks/my-webhook")
+ */
+export function findWebhook({
+    apiDefinition,
+    webhookId
+}: {
+    apiDefinition: ApiDefinition.ApiDefinition;
+    webhookId: string;
+}): ApiDefinition.WebhookDefinition | undefined {
+    const webhooks = Object.values(apiDefinition.webhooks);
+
+    // First, try to find by exact ID match
+    const webhookById = webhooks.find((w) => w.id === webhookId);
+    if (webhookById != null) {
+        return webhookById;
+    }
+
+    // Then, try to find by operationId match (exact)
+    const webhookByOperationId = webhooks.find((w) => w.operationId === webhookId);
+    if (webhookByOperationId != null) {
+        return webhookByOperationId;
+    }
+
+    // Then, try to find by operationId match with camelCase to kebab-case conversion
+    // e.g., "onOrderCreated" -> "on-order-created"
+    const kebabWebhookId = camelToKebab(webhookId);
+    if (kebabWebhookId !== webhookId) {
+        const webhookByKebabOperationId = webhooks.find((w) => w.operationId === kebabWebhookId);
+        if (webhookByKebabOperationId != null) {
+            return webhookByKebabOperationId;
+        }
+    }
+
+    // Then, try to find by ID suffix (part after the last dot)
+    // e.g., "onOrderCreated" matches "subpackage_orders.onOrderCreated"
+    const webhooksBySuffix = webhooks.filter((w) => {
+        const lastDotIndex = w.id.lastIndexOf(".");
+        if (lastDotIndex === -1) {
+            return false;
+        }
+        const suffix = w.id.slice(lastDotIndex + 1);
+        return suffix === webhookId;
+    });
+    // Only return if there's exactly one match to avoid ambiguity
+    if (webhooksBySuffix.length === 1) {
+        return webhooksBySuffix[0];
+    }
+
+    // Then, try to find by path match
+    const normalizedPath = webhookId.startsWith("/") ? webhookId : `/${webhookId}`;
+    const webhookByPath = webhooks.find((w) => {
+        const webhookPath = "/" + w.path.join("/");
+        return webhookPath === normalizedPath;
+    });
+
+    return webhookByPath;
+}

packages/fern-docs/bundle/src/mdx/bundler/serialize.ts

@@ -62,6 +62,7 @@ import { rehypeSchema } from "../plugins/rehype-schema";
 import { rehypeSteps } from "../plugins/rehype-steps";
 import { rehypeTable } from "../plugins/rehype-table";
 import { rehypeTabs } from "../plugins/rehype-tabs";
+import { rehypeWebhookPayloadSnippet } from "../plugins/rehype-webhook-payload-snippet";
 import { remarkExtractTitle } from "../plugins/remark-extract-title";
 import { trackCustomComponents } from "./track-custom-components";
 
@@ -254,6 +255,7 @@ async function serializeMdxImpl(
                     rehypeButtons,
                     [rehypeEndpointSchemaSnippets, { loader }],
                     [rehypeEndpointExampleSnippets, { loader }],
+                    [rehypeWebhookPayloadSnippet, { loader }],
                     [rehypeSchema, { loader }],
                     [rehypeRunnableEndpoint, { loader }],
                     [rehypeLang, { loader }],

packages/fern-docs/bundle/src/mdx/components/index.tsx

@@ -52,7 +52,8 @@ import {
     MergeAccessedThirdPartyEndpointsWidget,
     MergeSupportedFieldsByIntegrationWidget,
     Schema,
-    SchemaSnippet
+    SchemaSnippet,
+    WebhookPayloadSnippet
 } from "./snippets";
 import { EndpointSchemaSnippet } from "./snippets/EndpointSchemaSnippet";
 import { Step, StepGroup } from "./steps";
@@ -106,6 +107,7 @@ const FERN_COMPONENTS = {
     Schema,
     SchemaSnippet,
     SearchBar: SearchV2Trigger,
+    WebhookPayloadSnippet,
     Step,
     StepGroup,
     Tab,

packages/fern-docs/bundle/src/mdx/components/snippets/WebhookPayloadSnippet.tsx

@@ -0,0 +1,80 @@
+import type { ApiDefinition } from "@fern-api/fdr-sdk";
+import { CodeSnippetExample } from "@fern-docs/components/api-reference/examples/CodeSnippetExample";
+import { cn } from "@fern-docs/components/cn";
+import { t } from "@fern-docs/i18n";
+
+export function WebhookPayloadSnippet({
+    webhookDefinition,
+    slug,
+    className,
+    lang
+}: {
+    /**
+     * The webhook locator to use for the payload snippet.
+     * This can be the webhook ID or path.
+     */
+    webhook?: string;
+    /**
+     * @internal the rehype-webhook-payload-snippet plugin will set this
+     */
+    webhookDefinition?: ApiDefinition.WebhookDefinition;
+    /**
+     * The slug of the webhook.
+     */
+    slug: string | undefined;
+    className?: string;
+    lang?: string;
+}) {
+    if (webhookDefinition == null) {
+        return null;
+    }
+
+    return (
+        <WebhookPayloadSnippetInternal
+            webhook={webhookDefinition}
+            slug={slug}
+            className={className}
+            lang={lang ?? "en"}
+        />
+    );
+}
+
+function WebhookPayloadSnippetInternal({
+    webhook,
+    slug,
+    className,
+    lang
+}: {
+    slug: string | undefined;
+    webhook: ApiDefinition.WebhookDefinition;
+    className?: string;
+    lang: string;
+}) {
+    const example = webhook.examples?.[0];
+
+    if (example == null) {
+        return null;
+    }
+
+    const payloadJson = example.payload;
+
+    if (payloadJson == null) {
+        return null;
+    }
+
+    const payloadJsonString = JSON.stringify(payloadJson, null, 2);
+
+    return (
+        <div className={cn("mb-5 mt-3", className)}>
+            <CodeSnippetExample
+                title={t(lang).apiReference.payload}
+                code={payloadJsonString}
+                language="json"
+                json={payloadJson}
+                scrollAreaStyle={{ maxHeight: "500px" }}
+                slug={slug}
+                lang={lang}
+            />
+        </div>
+    );
+}

packages/fern-docs/bundle/src/mdx/components/snippets/index.ts

@@ -4,3 +4,4 @@ export * from "./MergeAccessedThirdPartyEndpointsWidget";
 export * from "./MergeSupportedFieldsByIntegrationWidget";
 export * from "./Schema";
 export * from "./SchemaSnippet";
+export * from "./WebhookPayloadSnippet";

packages/fern-docs/bundle/src/mdx/plugins/rehype-webhook-payload-snippet.ts

@@ -0,0 +1,74 @@
+import type { DocsLoader } from "@fern-api/docs-server/docs-loader";
+import {
+    CONTINUE,
+    type Hast,
+    hastMdxJsxElementHastToProps,
+    isMdxJsxElementHast,
+    SKIP,
+    type Unified,
+    unknownToMdxJsxAttribute,
+    visit
+} from "@fern-docs/mdx";
+
+/**
+ * This rehype plugin processes `WebhookPayloadSnippet` components in MDX content.
+ * It looks up the webhook definition by the provided `webhook` prop (ID or path)
+ * and injects the full webhook definition into the component props.
+ */
+export const rehypeWebhookPayloadSnippet: Unified.Plugin<[{ loader: DocsLoader }?], Hast.Root> = (opts) => {
+    if (!opts) {
+        return;
+    }
+    const loader = opts.loader;
+
+    return async (ast: Hast.Root) => {
+        const promises: Promise<void>[] = [];
+
+        visit(ast, (node, index, parent) => {
+            if (!isMdxJsxElementHast(node) || index == null || parent == null) {
+                return CONTINUE;
+            }
+
+            const isWebhookPayloadSnippet = node.name === "WebhookPayloadSnippet";
+
+            if (isWebhookPayloadSnippet) {
+                const { props } = hastMdxJsxElementHastToProps(node);
+
+                // cannot parse non-string webhook prop
+                if (typeof props.webhook !== "string") {
+                    return CONTINUE;
+                }
+
+                const webhookId = props.webhook;
+
+                promises.push(
+                    (async () => {
+                        try {
+                            const result = await loader.getWebhookByLocator(webhookId);
+
+                            if (result != null) {
+                                node.attributes.push(
+                                    unknownToMdxJsxAttribute("webhookDefinition", result.webhook),
+                                    unknownToMdxJsxAttribute("slug", result.slug)
+                                );
+                            } else {
+                                console.warn(`Could not find webhook for ${webhookId}`);
+                            }
+                        } catch (e) {
+                            console.error(`Error looking up webhook ${webhookId}`, e);
+                        }
+                    })()
+                );
+
+                return SKIP;
+            }
+
+            return CONTINUE;
+        });
+
+        if (promises.length > 0) {
+            // wait for all promises to resolve before proceeding
+            await Promise.all(promises);
+        }
+    };
+};