Docs: restructure Extend section with API, Webhooks, and Apps pages by FelixMalfait · Pull Request #18517 · twentyhq/twenty

FelixMalfait · 2026-03-10T08:14:53Z

Summary

Restructures the developer Extend documentation: moves API and Webhooks to top-level pages, creates dedicated Apps section with Getting Started, Building, and Publishing pages
Updates navigation structure (docs.json, base-structure.json, navigation.template.json)
Updates translated docs for all locales and LLMS.md references across app packages

Test plan

Run mintlify dev locally and verify navigation structure
Check that all links in the Extend section work correctly
Verify translated pages render properly

Made with Cursor

Restructures the developer documentation Extend section: - Moves API and Webhooks to top-level pages under Extend - Creates dedicated Apps section with Getting Started, Building, and Publishing pages - Updates navigation structure (docs.json, base-structure.json) - Updates translated docs for all locales - Updates LLMS.md references across app packages Made-with: Cursor

greptile-apps

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

Made-with: Cursor

cubic-dev-ai

9 issues found across 96 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/twenty-apps/internal/call-recording/LLMS.md">

<violation number="1" location="packages/twenty-apps/internal/call-recording/LLMS.md:4">
P2: The updated Rich app example link points to a repository path that does not exist, so readers will hit a 404.</violation>
</file>

<file name="packages/twenty-docs/developers/extend/webhooks.mdx">

<violation number="1" location="packages/twenty-docs/developers/extend/webhooks.mdx:102">
P1: The webhook signature check uses direct `===` comparison instead of a constant-time comparison, which weakens signature verification security.</violation>
</file>

<file name="packages/twenty-apps/community/apollo-enrich/LLMS.md">

<violation number="1" location="packages/twenty-apps/community/apollo-enrich/LLMS.md:4">
P2: The updated “Rich app example” URL points to a non-existent repository path, so readers will hit a broken link.</violation>
</file>

<file name="packages/twenty-docs/developers/extend/apps/building.mdx">

<violation number="1" location="packages/twenty-docs/developers/extend/apps/building.mdx:86">
P3: This example uses a quoted template placeholder (`'${PostCardStatus.DRAFT}'`), which won’t evaluate and will set the literal string. Use the enum value directly so the sample code is correct.</violation>
</file>

<file name="packages/twenty-docs/l/cs/developers/extend/extend.mdx">

<violation number="1" location="packages/twenty-docs/l/cs/developers/extend/extend.mdx:24">
P2: This link now targets /l/cs/developers/api, but the Czech API page still lives under extend/capabilities/apis.mdx, so this href will 404.</violation>

<violation number="2" location="packages/twenty-docs/l/cs/developers/extend/extend.mdx:27">
P2: This link now targets /l/cs/developers/webhooks, but the Czech webhooks page still lives under extend/capabilities/webhooks.mdx, so this href will 404.</violation>

<violation number="3" location="packages/twenty-docs/l/cs/developers/extend/extend.mdx:30">
P2: This link now targets /l/cs/developers/apps/apps, but the Czech apps page still lives under extend/capabilities/apps.mdx, so this href will 404.</violation>
</file>

<file name="packages/twenty-docs/l/ar/user-guide/getting-started/capabilities/what-is-twenty.mdx">

<violation number="1" location="packages/twenty-docs/l/ar/user-guide/getting-started/capabilities/what-is-twenty.mdx:38">
P2: The updated internal docs link points to a path that does not exist, which will create a broken navigation link.</violation>
</file>

<file name="packages/twenty-docs/docs.json">

<violation number="1" location="packages/twenty-docs/docs.json:361">
P2: The legacy "/developers/api-and-webhooks" redirect still targets "/developers/extend/extend", but that page was removed from navigation in this change. Update the redirect to a valid new Extend landing page (e.g., the new API overview) so old links don’t land on a missing page.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

packages/twenty-docs/developers/extend/webhooks.mdx

cubic-dev-ai · 2026-03-10T08:23:00Z

packages/twenty-apps/internal/call-recording/LLMS.md


 - Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app


P2: The updated Rich app example link points to a repository path that does not exist, so readers will hit a 404.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-apps/internal/call-recording/LLMS.md, line 4: <comment>The updated Rich app example link points to a repository path that does not exist, so readers will hit a 404.</comment> <file context> @@ -1,7 +1,7 @@ - Documentation: https://docs.twenty.com/developers/extend/capabilities/apps -- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app +- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app ## Common Pitfalls </file context>

cubic-dev-ai · 2026-03-10T08:23:00Z

packages/twenty-apps/community/apollo-enrich/LLMS.md


 - Documentation: https://docs.twenty.com/developers/extend/capabilities/apps
- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app
+- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app


P2: The updated “Rich app example” URL points to a non-existent repository path, so readers will hit a broken link.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-apps/community/apollo-enrich/LLMS.md, line 4: <comment>The updated “Rich app example” URL points to a non-existent repository path, so readers will hit a broken link.</comment> <file context> @@ -1,7 +1,7 @@ - Documentation: https://docs.twenty.com/developers/extend/capabilities/apps -- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/cli/__tests__/apps/rich-app +- Rich app example: https://github.com/twentyhq/twenty/tree/main/packages/twenty-sdk/src/app-seeds/rich-app ## UUID requirement </file context>

cubic-dev-ai · 2026-03-10T08:23:00Z

packages/twenty-docs/l/cs/developers/extend/extend.mdx

    Dostávejte oznámení o událostech v reálném čase
  </Card>
-  <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/extend/capabilities/apps">
+  <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/apps/apps">


P2: This link now targets /l/cs/developers/apps/apps, but the Czech apps page still lives under extend/capabilities/apps.mdx, so this href will 404.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/l/cs/developers/extend/extend.mdx, line 30: <comment>This link now targets /l/cs/developers/apps/apps, but the Czech apps page still lives under extend/capabilities/apps.mdx, so this href will 404.</comment> <file context> @@ -20,13 +21,13 @@ Twenty je navrženo tak, aby bylo rozšiřitelné. Použijte naše rozhraní API Dostávejte oznámení o událostech v reálném čase </Card> - <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/extend/capabilities/apps"> + <Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/apps/apps"> Vytvářejte přizpůsobení jako kód (Alpha) </Card> </file context>

Suggested change

<Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/apps/apps">

<Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/extend/capabilities/apps">

cubic-dev-ai · 2026-03-10T08:23:01Z

packages/twenty-docs/l/cs/developers/extend/extend.mdx

    Programově se připojte k Twenty
  </Card>
-  <Card title="Webhooky" icon="bell" href="/l/cs/developers/extend/capabilities/webhooks">
+  <Card title="Webhooky" icon="bell" href="/l/cs/developers/webhooks">


P2: This link now targets /l/cs/developers/webhooks, but the Czech webhooks page still lives under extend/capabilities/webhooks.mdx, so this href will 404.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/l/cs/developers/extend/extend.mdx, line 27: <comment>This link now targets /l/cs/developers/webhooks, but the Czech webhooks page still lives under extend/capabilities/webhooks.mdx, so this href will 404.</comment> <file context> @@ -20,13 +21,13 @@ Twenty je navrženo tak, aby bylo rozšiřitelné. Použijte naše rozhraní API Programově se připojte k Twenty </Card> - <Card title="Webhooky" icon="bell" href="/l/cs/developers/extend/capabilities/webhooks"> + <Card title="Webhooky" icon="bell" href="/l/cs/developers/webhooks"> Dostávejte oznámení o událostech v reálném čase </Card> </file context>

Suggested change

<Card title="Webhooky" icon="bell" href="/l/cs/developers/webhooks">

<Card title="Webhooky" icon="bell" href="/l/cs/developers/extend/capabilities/webhooks">

cubic-dev-ai · 2026-03-10T08:23:01Z

packages/twenty-docs/l/cs/developers/extend/extend.mdx


 <CardGroup cols={2}>
-  <Card title="API" icon="kód" href="/l/cs/developers/extend/capabilities/apis">
+  <Card title="API" icon="kód" href="/l/cs/developers/api">


P2: This link now targets /l/cs/developers/api, but the Czech API page still lives under extend/capabilities/apis.mdx, so this href will 404.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/l/cs/developers/extend/extend.mdx, line 24: <comment>This link now targets /l/cs/developers/api, but the Czech API page still lives under extend/capabilities/apis.mdx, so this href will 404.</comment> <file context> @@ -20,13 +21,13 @@ Twenty je navrženo tak, aby bylo rozšiřitelné. Použijte naše rozhraní API <CardGroup cols={2}> - <Card title="API" icon="kód" href="/l/cs/developers/extend/capabilities/apis"> + <Card title="API" icon="kód" href="/l/cs/developers/api"> Programově se připojte k Twenty </Card> </file context>

Suggested change

<Card title="API" icon="kód" href="/l/cs/developers/api">

<Card title="API" icon="kód" href="/l/cs/developers/extend/capabilities/apis">

cubic-dev-ai · 2026-03-10T08:23:01Z

packages/twenty-docs/l/ar/user-guide/getting-started/capabilities/what-is-twenty.mdx

 * **الأذونات والوصول:** تحكّم في مَن يمكنه عرض بياناتك وتحريرها وإدارتها باستخدام أذونات مستندة إلى الأدوار. [تكوين الوصول](/l/ar/user-guide/permissions-access/overview).
 * **الملاحظات والمهام:** أنشئ ملاحظات ومهام مرتبطة بسجلاتك لتحسين التعاون.
-* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/capabilities/apis).
+* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/api).


P2: The updated internal docs link points to a path that does not exist, which will create a broken navigation link.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/l/ar/user-guide/getting-started/capabilities/what-is-twenty.mdx, line 38: <comment>The updated internal docs link points to a path that does not exist, which will create a broken navigation link.</comment> <file context> @@ -35,7 +35,7 @@ description: Twenty هو نظام إدارة علاقات العملاء (CRM) * **الأذونات والوصول:** تحكّم في مَن يمكنه عرض بياناتك وتحريرها وإدارتها باستخدام أذونات مستندة إلى الأدوار. [تكوين الوصول](/l/ar/user-guide/permissions-access/overview). * **الملاحظات والمهام:** أنشئ ملاحظات ومهام مرتبطة بسجلاتك لتحسين التعاون. -* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/capabilities/apis). +* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/api). ## انضم الآن </file context>

Suggested change

* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/api).

* **واجهة برمجة التطبيقات والويب هوكس:** الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/capabilities/apis).

packages/twenty-docs/docs.json

cubic-dev-ai · 2026-03-10T08:23:01Z

packages/twenty-docs/developers/extend/apps/building.mdx

+      type: FieldType.SELECT,
+      label: 'Status',
+      icon: 'IconSend',
+      defaultValue: `'${PostCardStatus.DRAFT}'`,


P3: This example uses a quoted template placeholder ('${PostCardStatus.DRAFT}'), which won’t evaluate and will set the literal string. Use the enum value directly so the sample code is correct.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/developers/extend/apps/building.mdx, line 86: <comment>This example uses a quoted template placeholder (`'${PostCardStatus.DRAFT}'`), which won’t evaluate and will set the literal string. Use the enum value directly so the sample code is correct.</comment> <file context> @@ -0,0 +1,677 @@ + type: FieldType.SELECT, + label: 'Status', + icon: 'IconSend', + defaultValue: `'${PostCardStatus.DRAFT}'`, + options: [ + { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' }, </file context>

- Use crypto.timingSafeEqual() instead of === for constant-time signature comparison in the webhook validation example - Update /developers/api-and-webhooks redirect to point to /developers/extend/api instead of removed extend landing page Made-with: Cursor

cubic-dev-ai

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/twenty-docs/developers/extend/webhooks.mdx">

<violation number="1" location="packages/twenty-docs/developers/extend/webhooks.mdx:103">
P2: Guard the received signature before calling `timingSafeEqual`; otherwise invalid/missing headers can throw and break webhook handling instead of cleanly failing validation.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

cubic-dev-ai · 2026-03-10T08:32:42Z

packages/twenty-docs/developers/extend/webhooks.mdx

+  .digest("hex");
+
+const receivedSignature = req.headers["x-twenty-webhook-signature"];
+const isValid = crypto.timingSafeEqual(


P2: Guard the received signature before calling timingSafeEqual; otherwise invalid/missing headers can throw and break webhook handling instead of cleanly failing validation.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/twenty-docs/developers/extend/webhooks.mdx, line 103: <comment>Guard the received signature before calling `timingSafeEqual`; otherwise invalid/missing headers can throw and break webhook handling instead of cleanly failing validation.</comment> <file context> @@ -99,7 +99,11 @@ const expectedSignature = crypto -const isValid = expectedSignature === req.headers["x-twenty-webhook-signature"]; +const receivedSignature = req.headers["x-twenty-webhook-signature"]; +const isValid = crypto.timingSafeEqual( + Buffer.from(expectedSignature, "hex"), + Buffer.from(receivedSignature, "hex") </file context>

twenty-eng-sync · 2026-03-10T09:02:06Z

Hey @FelixMalfait! After you've done the QA of your Pull Request, you can mark it as done here. Thank you!

greptile-apps bot reviewed Mar 10, 2026

View reviewed changes

chore: sync docs artifacts

10f66b8

mintlify bot deployed to staging - packages/twenty-docs March 10, 2026 08:16 View deployment

FelixMalfait added a commit that referenced this pull request Mar 10, 2026

Extract docs changes to separate PR (#18517)

f57677c

Made-with: Cursor

cubic-dev-ai bot reviewed Mar 10, 2026

View reviewed changes

mintlify bot deployed to staging - packages/twenty-docs March 10, 2026 08:31 View deployment

cubic-dev-ai bot reviewed Mar 10, 2026

View reviewed changes

FelixMalfait merged commit 882e9fd into main Mar 10, 2026
104 of 112 checks passed

FelixMalfait deleted the docs/restructure-extend-apps branch March 10, 2026 09:00

	<Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/apps/apps">
	<Card title="Aplikace" icon="puzzle-piece" href="/l/cs/developers/extend/capabilities/apps">

	<Card title="Webhooky" icon="bell" href="/l/cs/developers/webhooks">
	<Card title="Webhooky" icon="bell" href="/l/cs/developers/extend/capabilities/webhooks">

	<Card title="API" icon="kód" href="/l/cs/developers/api">
	<Card title="API" icon="kód" href="/l/cs/developers/extend/capabilities/apis">

	* واجهة برمجة التطبيقات والويب هوكس: الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/api).
	* واجهة برمجة التطبيقات والويب هوكس: الاتصال بالتطبيقات الأخرى وإنشاء عمليات تكامل مخصصة. [ابدأ التكامل](/l/ar/developers/extend/capabilities/apis).

Conversation

FelixMalfait commented Mar 10, 2026

Summary

Test plan

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai bot Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

twenty-eng-sync bot commented Mar 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading

cubic-dev-ai bot Mar 10, 2026 •

edited

Loading