Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| # Build Your Own Extension Server | ||
|
|
||
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash and changed passive voice to active
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec. | |
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language—the contract defines this using an OpenAPI 3.0 spec. |
|
|
||
| ## OpenAPI spec | ||
|
|
||
| The canonical contract is maintained in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository: |
There was a problem hiding this comment.
Google.Passive: Changed from passive to active voice
| The canonical contract is maintained in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository: | |
| The [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository maintains the canonical contract: |
| oapi-codegen -generate types,server -package server schema.yaml | ||
| ``` | ||
|
|
||
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach — see `pkg/server/` for the generated types. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach — see `pkg/server/` for the generated types. | |
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach—see `pkg/server/` for the generated types. |
|
|
||
| ## Endpoints to implement | ||
|
|
||
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash and changed passive voice to active
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below. | |
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard—the defaults appear below. |
| | `only` | object | If present, **only** these tools are allowed (deny list ignored) | | ||
| | `deny` | object | Tools listed here are denied (ignored if `only` is present) | | ||
|
|
||
| If you return neither field, the Arcade treats it as "no change" — all tools remain allowed at this hook. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash
| If you return neither field, the Arcade treats it as "no change" — all tools remain allowed at this hook. | |
| If you return neither field, the Arcade treats it as "no change"—all tools remain allowed at this hook. |
|
|
||
| ## Why use Logic Extensions? | ||
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system |
There was a problem hiding this comment.
Google.EmDash: Remove spaces around em dash
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | |
| - **Access control**—Delegate "can this user see/use this tool?" to your IDP or entitlement system |
| ## Why use Logic Extensions? | ||
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) |
There was a problem hiding this comment.
Google.EmDash and Google.Latin: Remove spaces around em dash and replace 'e.g.' with 'for example'
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | |
| - **Request validation**—Enforce policies before execution (for example, block certain domains, require org-scoped inputs) |
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | ||
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content |
There was a problem hiding this comment.
Google.EmDash: Remove spaces around em dash
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content | |
| - **Payload modification**—Enrich inputs, inject secrets, redact PII from outputs, or filter content |
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | ||
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content | ||
| - **Audit and compliance** — Route all tool interactions through your security and logging infrastructure |
There was a problem hiding this comment.
Google.EmDash: Remove spaces around em dash
| - **Audit and compliance** — Route all tool interactions through your security and logging infrastructure | |
| - **Audit and compliance**—Route all tool interactions through your security and logging infrastructure |
|
|
||
| # API Reference | ||
|
|
||
| This is the interactive documentation for the **Logic Extensions webhook contract** — the HTTP interface your server implements to integrate with the Arcade Engine. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around the em dash as required by Google style guide
| This is the interactive documentation for the **Logic Extensions webhook contract** — the HTTP interface your server implements to integrate with the Arcade Engine. | |
| This is the interactive documentation for the **Logic Extensions webhook contract**—the HTTP interface your server implements to integrate with the Arcade Engine. |
|
|
||
| # Build Your Own Extension Server | ||
|
|
||
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash and changed to active voice
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language — the contract is defined by an OpenAPI 3.0 spec. | |
| This guide walks through implementing a webhook server that satisfies the Logic Extensions contract. You can write it in any language—the contract defines an OpenAPI 3.0 spec. |
|
|
||
| ## OpenAPI spec | ||
|
|
||
| The canonical contract is maintained in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository: |
There was a problem hiding this comment.
Google.Passive: Changed to active voice
| The canonical contract is maintained in the [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository: | |
| The [ArcadeAI/schemas](https://github.com/ArcadeAI/schemas) repository maintains the canonical contract: |
| oapi-codegen -generate types,server -package server schema.yaml | ||
| ``` | ||
|
|
||
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach — see `pkg/server/` for the generated types. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach — see `pkg/server/` for the generated types. | |
| The [logic-extensions-examples](https://github.com/ArcadeAI/logic-extensions-examples) repo uses this approach—see `pkg/server/` for the generated types. |
|
|
||
| ## Endpoints to implement | ||
|
|
||
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash and changed to active voice
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard — the defaults are shown below. | |
| Your server needs to expose HTTP POST endpoints for each hook point you want to handle. Endpoint paths are fully configurable in the Dashboard—the defaults appear below. |
| | `only` | object | If present, **only** these tools are allowed (deny list ignored) | | ||
| | `deny` | object | Tools listed here are denied (ignored if `only` is present) | | ||
|
|
||
| If you return neither field, the Arcade treats it as "no change" — all tools remain allowed at this hook. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around em dash
| If you return neither field, the Arcade treats it as "no change" — all tools remain allowed at this hook. | |
| If you return neither field, the Arcade treats it as "no change"—all tools remain allowed at this hook. |
|
|
||
| ## Why use Logic Extensions? | ||
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system |
There was a problem hiding this comment.
Google.EmDash: Remove spaces before and after em dash
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | |
| - **Access control**—Delegate "can this user see/use this tool?" to your IDP or entitlement system |
| ## Why use Logic Extensions? | ||
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) |
There was a problem hiding this comment.
Google.EmDash and Google.Latin: Remove spaces around em dash and replace 'e.g.' with 'for example'
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | |
| - **Request validation**—Enforce policies before execution (for example, block certain domains, require org-scoped inputs) |
|
|
||
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | ||
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content |
There was a problem hiding this comment.
Google.EmDash: Remove spaces before and after em dash
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content | |
| - **Payload modification**—Enrich inputs, inject secrets, redact PII from outputs, or filter content |
| - **Access control** — Delegate "can this user see/use this tool?" to your IDP or entitlement system | ||
| - **Request validation** — Enforce policies before execution (e.g., block certain domains, require org-scoped inputs) | ||
| - **Payload modification** — Enrich inputs, inject secrets, redact PII from outputs, or filter content | ||
| - **Audit and compliance** — Route all tool interactions through your security and logging infrastructure |
There was a problem hiding this comment.
Google.EmDash: Remove spaces before and after em dash
| - **Audit and compliance** — Route all tool interactions through your security and logging infrastructure | |
| - **Audit and compliance**—Route all tool interactions through your security and logging infrastructure |
|
|
||
| # API Reference | ||
|
|
||
| This is the interactive documentation for the **Logic Extensions webhook contract** — the HTTP interface your server implements to integrate with the Arcade Engine. |
There was a problem hiding this comment.
Google.EmDash: Removed spaces around the em dash per Google style guide
| This is the interactive documentation for the **Logic Extensions webhook contract** — the HTTP interface your server implements to integrate with the Arcade Engine. | |
| This is the interactive documentation for the **Logic Extensions webhook contract**—the HTTP interface your server implements to integrate with the Arcade Engine. |
| Arcade sends one of: | ||
|
|
||
| - **Bearer:** `Authorization: Bearer <token>` (token from extension config) | ||
| - **mTLS:** Client certificate during TLS handshake; optional CA cert for server verification |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Duplicate page conflicts with redirect for deleted path
Medium Severity
The file app/en/guides/logic-extensions/build-your-own/page.mdx is a near-duplicate of app/en/guides/contextual-access/build-your-own/page.mdx, yet a permanent redirect from the same logic-extensions/build-your-own path to contextual-access/build-your-own is configured in next.config.ts. The redirect comment says "Auto-added redirects for deleted pages," indicating this file was supposed to be removed. It either creates a conflict with the redirect or is unreachable dead code, and its slightly different wording ("Logic Extensions contract" vs "Contextual Access Webhook contract") could cause confusion if the redirect doesn't take priority.
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| description: Unauthorized - invalid or missing bearer token |
There was a problem hiding this comment.
Missing 401 response body schema on /pre endpoint
Low Severity
The /pre endpoint's 401 response defines only a description with no content or schema, while the /post and /access endpoints both include an ErrorResponse body for their 401 responses. This inconsistency will cause OpenAPI code generators (which the docs recommend) to produce different types for the 401 response across endpoints, making client implementations unnecessarily inconsistent.
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Duplicate unreachable page alongside redirect rule
Low Severity
This entire file is a near-exact duplicate of app/en/guides/contextual-access/build-your-own/page.mdx, and a redirect in next.config.ts already routes /:locale/guides/logic-extensions/build-your-own to the contextual-access version. Since Next.js redirects run before page resolution, this page is unreachable dead code. It also lacks a corresponding _meta.tsx, so it won't appear in navigation. Having two copies risks them diverging silently during future edits.
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| description: Unauthorized - invalid or missing bearer token |
There was a problem hiding this comment.
OpenAPI spec /pre 401 response missing body schema
Medium Severity
The /pre endpoint's 401 response only has a description with no content schema, while the /post and /access endpoints both define a 401 response body with ErrorResponse. This inconsistency means code generators will produce different client types for the pre-hook — expecting no response body on 401 — compared to the other two hooks. Anyone generating server stubs or clients from this spec will get mismatched behavior for the /pre endpoint.
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Duplicate page overrides intended redirect at logic-extensions path
Medium Severity
A new page at app/en/guides/logic-extensions/build-your-own/page.mdx duplicates app/en/guides/contextual-access/build-your-own/page.mdx, while next.config.ts also adds a redirect from the same logic-extensions/build-your-own path to contextual-access/build-your-own. In Next.js, the page takes precedence over the redirect, making the redirect dead code. This is the only page under logic-extensions/ and has no _meta.tsx, suggesting it was accidentally left in.
Additional Locations (1)
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Unreachable duplicate page at redirected path
Low Severity
A full page file exists at app/en/guides/logic-extensions/build-your-own/page.mdx, but next.config.ts also defines a permanent redirect from /:locale/guides/logic-extensions/build-your-own to /:locale/guides/contextual-access/build-your-own. In Next.js, redirects are evaluated before filesystem pages, so this page is never served — it's dead code. There's also no _meta.tsx for the logic-extensions directory, so it won't appear in navigation.
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| description: Unauthorized - invalid or missing bearer token |
There was a problem hiding this comment.
OpenAPI spec 401 response inconsistent across endpoints
Medium Severity
The /pre endpoint's 401 response (lines 40–41) is missing the content block with ErrorResponse schema that the /post (lines 79–84) and /access (lines 121–126) endpoints both include. Code generators consuming this spec would produce inconsistent types for the 401 response across endpoints — /pre would have no response body type while the other two would have ErrorResponse.
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Page file overrides redirect causing duplicate content
Medium Severity
A page file exists at app/en/guides/logic-extensions/build-your-own/page.mdx while a redirect is also configured for /:locale/guides/logic-extensions/build-your-own → /:locale/guides/contextual-access/build-your-own. In Next.js, the page takes precedence, so the redirect never fires. This leaves duplicate content at two URLs instead of properly redirecting the old path to the new one. The page file likely needs to be removed.
Additional Locations (1)
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| description: Unauthorized - invalid or missing bearer token |
There was a problem hiding this comment.
Pre-hook 401 response missing body unlike other endpoints
Low Severity
The /pre endpoint's 401 response has no content body, while the /post and /access endpoints both define a content with ErrorResponse schema for their 401 responses. This inconsistency means code generators will produce different response types for the same error across hooks, which could cause runtime issues for anyone generating server stubs from this spec.
Additional Locations (1)
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Duplicate page at redirected logic-extensions path
Low Severity
This file is a near-duplicate of app/en/guides/contextual-access/build-your-own/page.mdx, and a permanent redirect already exists in next.config.ts from the logic-extensions path to the contextual-access path. Having both a page and a redirect for the same route creates unnecessary redundancy — the page either shadows the redirect or is dead code, and future updates risk drifting between the two copies.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 2 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
|
|
||
| - [API Reference](/references/contextual-access-webhook-api) — Interactive Swagger documentation for the full schema | ||
| - [Run an extension](/guides/contextual-access/examples) — Try the open-source example servers as reference | ||
| - [How Hooks Work](/guides/contextual-access/how-hooks-work) — Understand execution order, phases, and failure modes |
There was a problem hiding this comment.
Unreachable duplicate page behind redirect
Low Severity
This page is a near-duplicate of app/en/guides/contextual-access/build-your-own/page.mdx, and next.config.ts defines a permanent redirect from /guides/logic-extensions/build-your-own to /guides/contextual-access/build-your-own. Since Next.js redirects() are evaluated before filesystem routing, this page is unreachable. It also has no _meta.tsx in its parent directory, so it won't appear in navigation. This is dead code that adds maintenance burden.
| schema: | ||
| $ref: '#/components/schemas/ErrorResponse' | ||
| '401': | ||
| description: Unauthorized - invalid or missing bearer token |
There was a problem hiding this comment.
Pre-hook 401 response missing body schema unlike others
Low Severity
The /pre endpoint's 401 response only has a description and no content block, while both /post (lines 79–84) and /access (lines 121–126) define a content body with the ErrorResponse schema for their 401 responses. This inconsistency means code generators using this spec will produce different error-handling signatures for the pre-hook versus the other endpoints.
2 participants
Note
Low Risk
Documentation-only changes plus redirects and a client-side Swagger UI embed; low risk aside from potential broken links/redirect mistakes.
Overview
Introduces a new Contextual Access documentation section, including overview, hook execution semantics, examples, and a “build your own server” guide, and wires it into the Nextra navigation.
Adds a new interactive Swagger-based reference page for the Contextual Access webhook OpenAPI schema, plus a local
public/specs/logic-extensions-webhook.yamlspec artifact.Updates routing to redirect legacy
logic-extensionsandlogic-extensions-apiURLs to the new Contextual Access pages, and refreshes generated markdown/llms.txtoutputs (notably many “Last updated” timestamps and new reference links).Written by Cursor Bugbot for commit a56194a. This will update automatically on new commits. Configure here.