Skip to content

The open alternative to Salesforce, designed for AI.

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.mdx
index 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/:resolverLogicFunctionUniver
The 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.ts
index 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 } when
diff --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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 ExceptionFilter
undefined,
{ 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.ts
index 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/applic
import { 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.ts
index 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}`)[];
};