The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Let a server route declare which HTTP methods it answers (#24401)
Emmanuel Hernández Bazán4b12655f05be
diff --git a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdxindex 46d8e2b72a0..4153f8ce3e5 100644--- a/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx+++ b/packages/twenty-docs/developers/extend/apps/logic/logic-functions.mdx@@ -282,6 +282,28 @@ POST https://your-twenty-server.com/webhooks/server/:resolverLogicFunctionUniverThe identifier is the resolver's `universalIdentifier` from your manifest. Register that URL with the provider.+**Answering a verification GET.** Some providers verify an endpoint before they deliver to it, by sending a `GET` carrying a challenge to the same URL they will later `POST` events to — Meta's WhatsApp Cloud API is one. A server route answers `POST` only unless you say otherwise, so declare both methods:++```ts+serverRouteTriggerSettings: {+ forwardedRequestHeaders: ['x-hub-signature-256'],+ httpMethods: ['GET', 'POST'],+}+```++The challenge arrives in `event.queryStringParameters`, and returning a `Response` echoes it back to the provider on the same request. A string body is sent as `text/plain`, which is what these providers expect:++```ts+const handler = async (event: RoutePayload) => {+ if (event.requestContext.http.method === 'GET') {+ return new Response(event.queryStringParameters['hub.challenge']);+ }+ // …handle the delivered event+};+```++`httpMethods` replaces the default rather than adding to it, so `['GET']` alone makes the route reject `POST`. Only `GET` and `POST` are supported. Leave it unset unless the provider needs the second verb: a route that declares `GET` will have its resolver executed by any unauthenticated caller, including the crawlers and link unfurlers that send `GET` unprompted. Anything the platform does not have a method for is answered `405` without the resolver ever running.+<Note>**The application must be claimed and installed on its owner workspace.** Because the resolver runs in the **owner workspace** (the workspace that owns the application registration), a server route trigger only works once the application has been *claimed* — i.e. it has an owner workspace — **and** that application is **installed on the owner workspace**. Until both are true the resolver has nowhere to run, so the route cannot be dispatched. An application that exposes a `serverRouteTriggerSettings` logic function therefore cannot be listed in the marketplace until it is claimed and installed on its owner workspace.</Note>diff --git a/packages/twenty-sdk/src/sdk/define/logic-functions/__tests__/define-logic-function.spec.ts b/packages/twenty-sdk/src/sdk/define/logic-functions/__tests__/define-logic-function.spec.tsindex 73141e9e49c..7925596b6dd 100644--- a/packages/twenty-sdk/src/sdk/define/logic-functions/__tests__/define-logic-function.spec.ts+++ b/packages/twenty-sdk/src/sdk/define/logic-functions/__tests__/define-logic-function.spec.ts@@ -214,6 +214,38 @@ describe('defineLogicFunction', () => {expect(result.config.serverRouteTriggerSettings).toBeDefined();});+ it('accepts a serverRouteTriggerSettings resolver declaring GET and POST', () => {+ const result = defineLogicFunction({+ universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',+ name: 'Answer the provider verification challenge',+ serverRouteTriggerSettings: { httpMethods: ['GET', 'POST'] },+ handler: async () => ({+ workspaceId: 'ws-1',+ targetLogicFunctionUniversalIdentifier: 'target-uid',+ }),+ });++ expect(result.success).toBe(true);+ expect(result.errors).toEqual([]);+ });++ it('rejects a serverRouteTriggerSettings resolver declaring a method the server route does not serve', () => {+ const result = defineLogicFunction({+ universalIdentifier: 'e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf',+ name: 'Unroutable method',+ serverRouteTriggerSettings: { httpMethods: ['PUT'] },+ handler: async () => ({+ workspaceId: 'ws-1',+ targetLogicFunctionUniversalIdentifier: 'target-uid',+ }),+ });++ expect(result.success).toBe(false);+ expect(result.errors).toContain(+ 'Server route trigger only supports the GET and POST http methods',+ );+ });+it('compile-time rejects a serverRouteTriggerSettings resolver returning the wrong shape', () => {// @ts-expect-error — handler must return { workspaceId: string;// targetLogicFunctionUniversalIdentifier: string } whendiff --git a/packages/twenty-sdk/src/sdk/define/logic-functions/define-logic-function.ts b/packages/twenty-sdk/src/sdk/define/logic-functions/define-logic-function.tsindex bc3165ff432..b0595e88d14 100644--- a/packages/twenty-sdk/src/sdk/define/logic-functions/define-logic-function.ts+++ b/packages/twenty-sdk/src/sdk/define/logic-functions/define-logic-function.ts@@ -1,3 +1,5 @@+import { HTTPMethod } from 'twenty-shared/types';+import { type LogicFunctionConfig } from '@/sdk/define/logic-functions/logic-function-config';import { createValidationResult } from '@/sdk/define/common/utils/create-validation-result';import type { DefineEntity } from '@/sdk/define/common/types/define-entity.type';@@ -28,6 +30,17 @@ export const defineLogicFunction: DefineEntity<LogicFunctionConfig> = (}}+ if (+ config.serverRouteTriggerSettings?.httpMethods?.some(+ (httpMethod) =>+ httpMethod !== HTTPMethod.GET && httpMethod !== HTTPMethod.POST,+ )+ ) {+ errors.push(+ 'Server route trigger only supports the GET and POST http methods',+ );+ }+if (config.cronTriggerSettings) {if (!config.cronTriggerSettings.pattern) {errors.push('Cron trigger must have a pattern');diff --git a/packages/twenty-server/src/engine/core-modules/server-route-trigger/constants/default-server-route-http-methods.constant.ts b/packages/twenty-server/src/engine/core-modules/server-route-trigger/constants/default-server-route-http-methods.constant.tsnew file mode 100644index 00000000000..9a475bc764f--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/server-route-trigger/constants/default-server-route-http-methods.constant.ts@@ -0,0 +1,3 @@+import { HTTPMethod } from 'twenty-shared/types';++export const DEFAULT_SERVER_ROUTE_HTTP_METHODS = [HTTPMethod.POST];diff --git a/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger-rest-api-exception-filter.ts b/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger-rest-api-exception-filter.tsindex 9b0c5c032f9..ebf74cf376d 100644--- a/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger-rest-api-exception-filter.ts+++ b/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger-rest-api-exception-filter.ts@@ -81,6 +81,15 @@ export class ServerRouteTriggerRestApiExceptionFilter implements ExceptionFilterundefined,{ shouldBeCapturedBySentry: false },);+ case ServerRouteTriggerExceptionCode.METHOD_NOT_ALLOWED:+ return this.httpExceptionHandlerService.handleError(+ exception as CustomException,+ response,+ 405,+ undefined,+ undefined,+ { shouldBeCapturedBySentry: false },+ );default: {return this.httpExceptionHandlerService.handleError(exception as CustomException,diff --git a/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger.exception.ts b/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger.exception.tsindex 9b6ca198015..bbb145b2826 100644--- a/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger.exception.ts+++ b/packages/twenty-server/src/engine/core-modules/server-route-trigger/exceptions/server-route-trigger.exception.ts@@ -12,6 +12,7 @@ export enum ServerRouteTriggerExceptionCode {SERVER_ROUTE_PLATFORM_ERROR = 'SERVER_ROUTE_PLATFORM_ERROR',RESOLVER_INVALID_RESULT = 'RESOLVER_INVALID_RESULT',RESOLVER_REQUIRES_AUTHENTICATION = 'RESOLVER_REQUIRES_AUTHENTICATION',+ METHOD_NOT_ALLOWED = 'METHOD_NOT_ALLOWED',}const getServerRouteTriggerExceptionUserFriendlyMessage = (@@ -32,6 +33,8 @@ const getServerRouteTriggerExceptionUserFriendlyMessage = (return msg`Resolver logic function returned an invalid result.`;case ServerRouteTriggerExceptionCode.RESOLVER_REQUIRES_AUTHENTICATION:return msg`Server logic function requires authentication.`;+ case ServerRouteTriggerExceptionCode.METHOD_NOT_ALLOWED:+ return msg`This HTTP method is not allowed on this server route.`;default:assertUnreachable(code);}diff --git a/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.controller.ts b/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.controller.tsindex 75e80853bc6..84a027bfd4e 100644--- a/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.controller.ts+++ b/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.controller.ts@@ -1,5 +1,6 @@import {Controller,+ Get,Param,Post,Req,@@ -25,12 +26,10 @@ export class ServerRouteTriggerController {private readonly serverRouteTriggerService: ServerRouteTriggerService,) {}- @Post(':resolverLogicFunctionUniversalIdentifier')- async post(- @Param('resolverLogicFunctionUniversalIdentifier')+ private async handleRequest(resolverLogicFunctionUniversalIdentifier: string,- @Req() request: Request,- @Res() response: Response,+ request: Request,+ response: Response,) {sendRouteTriggerResponse(response,@@ -40,4 +39,32 @@ export class ServerRouteTriggerController {}),);}++ @Get(':resolverLogicFunctionUniversalIdentifier')+ async get(+ @Param('resolverLogicFunctionUniversalIdentifier')+ resolverLogicFunctionUniversalIdentifier: string,+ @Req() request: Request,+ @Res() response: Response,+ ) {+ await this.handleRequest(+ resolverLogicFunctionUniversalIdentifier,+ request,+ response,+ );+ }++ @Post(':resolverLogicFunctionUniversalIdentifier')+ async post(+ @Param('resolverLogicFunctionUniversalIdentifier')+ resolverLogicFunctionUniversalIdentifier: string,+ @Req() request: Request,+ @Res() response: Response,+ ) {+ await this.handleRequest(+ resolverLogicFunctionUniversalIdentifier,+ request,+ response,+ );+ }}diff --git a/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.service.ts b/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.service.tsindex cf973a130be..0a228c5e10d 100644--- a/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.service.ts+++ b/packages/twenty-server/src/engine/core-modules/server-route-trigger/server-route-trigger.service.ts@@ -24,6 +24,7 @@ import {buildRouteTriggerResponse,type RouteTriggerResponse,} from 'src/engine/core-modules/logic-function/logic-function-trigger/triggers/route/utils/route-trigger-response.util';+import { DEFAULT_SERVER_ROUTE_HTTP_METHODS } from 'src/engine/core-modules/server-route-trigger/constants/default-server-route-http-methods.constant';import {ServerRouteTriggerException,ServerRouteTriggerExceptionCode,@@ -68,6 +69,19 @@ export class ServerRouteTriggerService {);}+ const allowedHttpMethods =+ resolver.serverRouteTriggerSettings?.httpMethods ??+ DEFAULT_SERVER_ROUTE_HTTP_METHODS;++ if (+ !allowedHttpMethods.some((httpMethod) => httpMethod === request.method)+ ) {+ throw new ServerRouteTriggerException(+ `Server resolver function ${resolverLogicFunctionUniversalIdentifier} does not accept ${request.method} requests`,+ ServerRouteTriggerExceptionCode.METHOD_NOT_ALLOWED,+ );+ }+if (resolver.httpRouteTriggerSettings?.isAuthRequired === true) {throw new ServerRouteTriggerException(`Server resolver function ${resolverLogicFunctionUniversalIdentifier} requires authentication and cannot be dispatched through the public server route`,diff --git a/packages/twenty-server/test/integration/server-route-trigger/suites/__snapshots__/server-route-trigger-authorization.integration-spec.ts.snap b/packages/twenty-server/test/integration/server-route-trigger/suites/__snapshots__/server-route-trigger-authorization.integration-spec.ts.snapindex 224da16ebd5..ed66d9e64b6 100644--- a/packages/twenty-server/test/integration/server-route-trigger/suites/__snapshots__/server-route-trigger-authorization.integration-spec.ts.snap+++ b/packages/twenty-server/test/integration/server-route-trigger/suites/__snapshots__/server-route-trigger-authorization.integration-spec.ts.snap@@ -1,5 +1,33 @@// Jest Snapshot v1, https://goo.gl/fbAQLP+exports[`ServerRouteTrigger authorization (integration) GET /webhooks/server/:universalIdentifier (public, unauthenticated) answers 404, not 405, for an identifier that resolves to nothing 1`] = `+{+ "body": {+ "code": "LOGIC_FUNCTION_NOT_FOUND",+ "error": "Error",+ "messages": [+ "Server resolver function 1a1f983f-5c1a-4c60-a3c8-7d0e2a4a11a1 not found",+ ],+ "statusCode": 404,+ },+ "status": 404,+}+`;++exports[`ServerRouteTrigger authorization (integration) GET /webhooks/server/:universalIdentifier (public, unauthenticated) rejects a GET on a resolver that did not declare it 1`] = `+{+ "body": {+ "code": "METHOD_NOT_ALLOWED",+ "error": "Error",+ "messages": [+ "Server resolver function 2b2f983f-5c1a-4c60-a3c8-7d0e2a4a22b2 does not accept GET requests",+ ],+ "statusCode": 405,+ },+ "status": 405,+}+`;+exports[`ServerRouteTrigger authorization (integration) POST /webhooks/server/:universalIdentifier (public, unauthenticated) rejects a server-route-exposed resolver that requires authentication before executing it 1`] = `{"body": {diff --git a/packages/twenty-server/test/integration/server-route-trigger/suites/server-route-trigger-authorization.integration-spec.ts b/packages/twenty-server/test/integration/server-route-trigger/suites/server-route-trigger-authorization.integration-spec.tsindex d9c38ba42b8..fce86b35b44 100644--- a/packages/twenty-server/test/integration/server-route-trigger/suites/server-route-trigger-authorization.integration-spec.ts+++ b/packages/twenty-server/test/integration/server-route-trigger/suites/server-route-trigger-authorization.integration-spec.ts@@ -5,8 +5,12 @@ import { setupApplicationForSync } from 'test/integration/metadata/suites/applicimport { syncApplication } from 'test/integration/metadata/suites/application/utils/sync-application.util';import { uploadApplicationFile } from 'test/integration/metadata/suites/application/utils/upload-application-file.util';import { expectOneNotInternalServerErrorHttpResponseSnapshot } from 'test/integration/utils/expect-one-not-internal-server-error-http-response-snapshot.util';-import { type LogicFunctionManifest } from 'twenty-shared/application';+import {+ type LogicFunctionManifest,+ type ServerRouteTriggerSettings,+} from 'twenty-shared/application';import { LOGIC_FUNCTION_HTTP_RESPONSE_MARKER } from 'twenty-shared/types';+import { isDefined } from 'twenty-shared/utils';import { SEED_APPLE_WORKSPACE_ID } from 'src/engine/workspace-manager/dev-seeder/core/constants/seeder-workspaces.constant';@@ -25,6 +29,8 @@ const TARGET_FUNCTION_UNIVERSAL_IDENTIFIER ='4d4f983f-5c1a-4c60-a3c8-7d0e2a4a44d4';const HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER ='5e5f983f-5c1a-4c60-a3c8-7d0e2a4a55e5';+const GET_HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER =+ '6f6f983f-5c1a-4c60-a3c8-7d0e2a4a66f6';const TARGET_FUNCTION_RESPONSE = { greeting: 'hello from target function' };@@ -43,6 +49,16 @@ const HANDSHAKE_RESOLVER_BUILT_HANDLER_CODE = `export const main = async (event)});`;+// Mirrors how a provider verifies a webhook: the challenge arrives in the query+// string of a GET, and the answer must be the bare value, not JSON.+const GET_HANDSHAKE_RESOLVER_BUILT_HANDLER_CODE = `export const main = async (event) => ({+ ${LOGIC_FUNCTION_HTTP_RESPONSE_MARKER}: true,+ status: 200,+ headers: { 'content-type': 'text/plain' },+ body: event.queryStringParameters['hub.challenge'],+});+`;+const TARGET_BUILT_HANDLER_CODE = `export const main = async () => (${JSON.stringify(TARGET_FUNCTION_RESPONSE,)});@@ -53,11 +69,13 @@ const buildLogicFunctionManifest = ({name,serverRouteExposed,authRequired,+ httpMethods,}: {universalIdentifier: string;name: string;serverRouteExposed: boolean;authRequired: boolean;+ httpMethods?: ServerRouteTriggerSettings['httpMethods'];}): LogicFunctionManifest => ({universalIdentifier,name,@@ -75,7 +93,12 @@ const buildLogicFunctionManifest = ({}: {}),...(serverRouteExposed- ? { serverRouteTriggerSettings: { forwardedRequestHeaders: [] } }+ ? {+ serverRouteTriggerSettings: {+ forwardedRequestHeaders: [],+ ...(isDefined(httpMethods) ? { httpMethods } : {}),+ },+ }: {}),});@@ -122,6 +145,11 @@ describe('ServerRouteTrigger authorization (integration)', () => {builtHandlerCode: HANDSHAKE_RESOLVER_BUILT_HANDLER_CODE,});+ await uploadBuiltHandlerFile({+ builtHandlerPath: 'dist/get-handshake-resolver.mjs',+ builtHandlerCode: GET_HANDSHAKE_RESOLVER_BUILT_HANDLER_CODE,+ });+await uploadBuiltHandlerFile({builtHandlerPath: 'dist/target-function.mjs',builtHandlerCode: TARGET_BUILT_HANDLER_CODE,@@ -157,6 +185,13 @@ describe('ServerRouteTrigger authorization (integration)', () => {serverRouteExposed: true,authRequired: false,}),+ buildLogicFunctionManifest({+ universalIdentifier: GET_HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER,+ name: 'get-handshake-resolver',+ serverRouteExposed: true,+ authRequired: false,+ httpMethods: ['GET', 'POST'],+ }),buildLogicFunctionManifest({universalIdentifier: TARGET_FUNCTION_UNIVERSAL_IDENTIFIER,name: 'target-function',@@ -219,4 +254,72 @@ describe('ServerRouteTrigger authorization (integration)', () => {});});});++ describe('GET /webhooks/server/:universalIdentifier (public, unauthenticated)', () => {+ it('rejects a GET on a resolver that did not declare it', async () => {+ const response = await request(baseUrl).get(+ `/webhooks/server/${EXPOSED_RESOLVER_UNIVERSAL_IDENTIFIER}`,+ );++ expect(response.status).toBe(405);+ expectOneNotInternalServerErrorHttpResponseSnapshot({+ status: response.status,+ body: response.body,+ });+ });++ // Express dispatches HEAD to the GET handler, so it reaches the same gate.+ it('rejects a HEAD on a resolver that did not declare it', async () => {+ const response = await request(baseUrl).head(+ `/webhooks/server/${EXPOSED_RESOLVER_UNIVERSAL_IDENTIFIER}`,+ );++ expect(response.status).toBe(405);+ });++ it('answers the verification challenge of a resolver that declared GET', async () => {+ const response = await request(baseUrl)+ .get(`/webhooks/server/${GET_HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER}`)+ .query({+ 'hub.mode': 'subscribe',+ 'hub.challenge': 'challenge-abc123',+ 'hub.verify_token': 'a-token',+ });++ expect(response.status).toBe(200);+ expect(response.headers['content-type']).toContain('text/plain');+ expect(response.text).toBe('challenge-abc123');+ }, 60000);++ // HEAD is not an HTTPMethod a resolver can declare, so it stays rejected even+ // on a route that answers GET, rather than executing the function for a+ // request that cannot carry the challenge back.+ it('rejects a HEAD on a resolver that declared GET', async () => {+ const response = await request(baseUrl).head(+ `/webhooks/server/${GET_HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER}`,+ );++ expect(response.status).toBe(405);+ });++ it('still dispatches a POST on a resolver that declared both methods', async () => {+ const response = await request(baseUrl)+ .post(`/webhooks/server/${GET_HANDSHAKE_RESOLVER_UNIVERSAL_IDENTIFIER}`)+ .send({ any: 'payload' });++ expect(response.status).toBe(200);+ }, 60000);++ it('answers 404, not 405, for an identifier that resolves to nothing', async () => {+ const response = await request(baseUrl).get(+ `/webhooks/server/${NON_EXPOSED_FUNCTION_UNIVERSAL_IDENTIFIER}`,+ );++ expect(response.status).toBe(404);+ expectOneNotInternalServerErrorHttpResponseSnapshot({+ status: response.status,+ body: response.body,+ });+ });+ });});diff --git a/packages/twenty-shared/src/application/serverRouteTriggerSettingsType.ts b/packages/twenty-shared/src/application/serverRouteTriggerSettingsType.tsindex 7a4f4911c4f..f00ae6bca17 100644--- a/packages/twenty-shared/src/application/serverRouteTriggerSettingsType.ts+++ b/packages/twenty-shared/src/application/serverRouteTriggerSettingsType.ts@@ -1,3 +1,6 @@+import { type HTTPMethod } from '@/types';+export type ServerRouteTriggerSettings = {forwardedRequestHeaders?: string[];+ httpMethods?: (HTTPMethod | `${HTTPMethod}`)[];};