@hed-hog/core 0.0.385 → 0.0.387

package/src/oauth/oauth.service.ts

@@ -89,12 +89,17 @@ export class OAuthService {
     this.providers.set(linkedin.getProviderType(), linkedin);
   }
 
-  async getAuthUrl(provider: user_account_provider_52222e2ecb_enum, callbackPath: string) {
+  async getAuthUrl(
+    provider: user_account_provider_52222e2ecb_enum,
+    callbackPath: string,
+    flow?: 'login' | 'register' | 'connect',
+    app?: string,
+  ) {
     const enabled = await this.isProviderEnabled(provider);
     if (!enabled) {
       throw new BadRequestException(`OAuth provider ${provider} is not enabled.`);
     }
-    return this.getProvider(provider).getAuthUrl(callbackPath);
+    return this.getProvider(provider).getAuthUrl(callbackPath, flow, app);
   }
 
   async getMobileAuthUrl(
@@ -137,15 +142,16 @@ export class OAuthService {
     flow: 'login' | 'register' | 'connect',
     redirectApp?: string,
   ) {
+    // `self` means "the hub handles it locally"; a resolvable app key means the hub
+    // forwards the callback back to that app (origin-bound).
+    const app = this.sanitizeAppKey(redirectApp) ?? OAuthService.WEB_STATE_SELF_APP;
+
     // Single, flow-less callback per provider: the flow (and the initiating app)
     // travel in the signed state, so only ONE redirect URI needs to be registered
-    // per provider in its OAuth console.
+    // per provider in its OAuth console. `flow`/`app` are forwarded so providers that
+    // need them (e.g. Microsoft Entra ID's backend bounce + `prompt=consent`) can adapt.
     const callbackPath = `/callback/${String(provider)}`;
-    const authUrl = await this.getAuthUrl(provider, callbackPath);
-
-    // Always carry the flow. `self` means "the hub handles it locally"; a resolvable
-    // app key means the hub forwards the callback back to that app (origin-bound).
-    const app = this.sanitizeAppKey(redirectApp) ?? OAuthService.WEB_STATE_SELF_APP;
+    const authUrl = await this.getAuthUrl(provider, callbackPath, flow, app);
 
     const url = new URL(authUrl);
     url.searchParams.set('state', this.buildWebState(app, flow));
@@ -549,6 +555,182 @@ export class OAuthService {
     return record?.redirect_uri ?? null;
   }
 
+  /** TTL for the short web-ref bounce token (Entra). Short: it briefly holds an encrypted profile. */
+  private readonly webRefTokenTtlMs = 2 * 60 * 1000;
+
+  /**
+   * Server-side bounce for providers whose authorization `code` is too large to
+   * safely ride a front-end app URL (Microsoft Entra ID). Exchanges the code here
+   * (once, under the callback lock), stores the resulting profile encrypted under
+   * an opaque single-use `ref`, and returns that `ref`. The app later redeems it via
+   * `redeemWebRef`, so the giant code never reaches a front-end ingress.
+   */
+  async beginWebRefCallback({
+    provider,
+    code,
+    state,
+    flow,
+    appOrigin,
+  }: {
+    provider: user_account_provider_52222e2ecb_enum;
+    code: string;
+    state?: string;
+    flow: 'login' | 'register' | 'connect';
+    appOrigin: string | null;
+  }): Promise<string> {
+    if (!code) {
+      throw new BadRequestException('Authorization code is required.');
+    }
+
+    // Match the redirect_uri used at authorize time (the API callback).
+    const settings = await this.setting.getSettingValues(['api-url']);
+    const apiRedirectUri = new URL(
+      '/oauth/microsoft-entra-id/callback',
+      String(settings['api-url'] ?? ''),
+    ).toString();
+
+    const callbackKey = this.buildCallbackKey(provider, flow, code);
+    const profile = await this.callbackCoordinator.execute(callbackKey, async () =>
+      this.getProvider(provider).getProfile(code, flow, apiRedirectUri),
+    );
+
+    const token = this.security.randomOpaque(24);
+    const signature = this.security.signHmacSha256(`oauth-web-ref:${token}`);
+    const tokenHash = this.security.hashSha256(token);
+    const expiresAt = new Date(Date.now() + this.webRefTokenTtlMs);
+    const profileEnc = this.security.encrypt(JSON.stringify(profile));
+
+    await this.prisma.$executeRaw(
+      Prisma.sql`
+        INSERT INTO oauth_web_ref_token (
+          token_hash, provider, flow_type, app_origin, profile_enc, expires_at, created_at
+        ) VALUES (
+          ${tokenHash},
+          ${String(provider).toLowerCase()},
+          ${flow},
+          ${appOrigin},
+          ${profileEnc},
+          ${expiresAt},
+          NOW()
+        )
+      `,
+    );
+
+    return `${token}.${signature}`;
+  }
+
+  /**
+   * Redeems a `ref` issued by `beginWebRefCallback`: single-use consume, origin-bind
+   * to the initiating app, then finalize the flow (sets the refresh cookie via `res`
+   * and returns `{ accessToken }`) — byte-for-byte the same response as `callback/login`.
+   */
+  async redeemWebRef({
+    res,
+    ref,
+    provider,
+    locale,
+    ipAddress,
+    userAgent,
+    userId,
+    requestOrigin,
+    requestReferer,
+  }: {
+    res: Response;
+    ref: string;
+    provider: user_account_provider_52222e2ecb_enum;
+    locale: string;
+    ipAddress: string;
+    userAgent: string;
+    userId?: number;
+    requestOrigin?: string;
+    requestReferer?: string;
+  }) {
+    const parts = String(ref ?? '').split('.');
+    const token = parts[0];
+    const signature = parts[1];
+
+    if (!token || !signature) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    if (!this.security.verifyHmacSha256(`oauth-web-ref:${token}`, signature)) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    const tokenHash = this.security.hashSha256(token);
+    const rows = await this.prisma.$queryRaw<
+      Array<{ profile_enc: string; flow_type: string; app_origin: string | null }>
+    >(
+      Prisma.sql`
+        UPDATE oauth_web_ref_token
+        SET consumed_at = NOW()
+        WHERE token_hash = ${tokenHash}
+          AND provider = ${String(provider).toLowerCase()}
+          AND expires_at > NOW()
+          AND consumed_at IS NULL
+        RETURNING profile_enc, flow_type, app_origin
+      `,
+    );
+
+    const row = rows[0];
+    if (!row) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.alreadyProcessed', locale, 'This OAuth callback was already processed. Start the sign-in flow again.'),
+      );
+    }
+
+    const flow = row.flow_type as 'login' | 'register' | 'connect';
+
+    // Origin-bind at redeem (the backend callback's Origin was Microsoft, so the
+    // usual handleCallback binding can't run there). Skip only when no app origin
+    // was recorded (the hub's own "self" flow).
+    if (row.app_origin) {
+      const expectedOrigin = this.normalizeOrigin(row.app_origin);
+      const boundOrigin =
+        this.normalizeOrigin(requestOrigin) ?? this.normalizeOrigin(requestReferer);
+      if (!boundOrigin || expectedOrigin !== boundOrigin) {
+        throw new BadRequestException(
+          getLocaleText('oauth.callback.invalidState', locale, 'OAuth callback origin is invalid. Start the sign-in flow again.'),
+        );
+      }
+    }
+
+    if (flow === 'connect' && !userId) {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    let profile: any;
+    try {
+      profile = JSON.parse(this.security.decrypt(row.profile_enc));
+    } catch {
+      throw new BadRequestException(
+        getLocaleText('oauth.callback.invalidState', locale, 'OAuth reference is invalid or expired. Start the sign-in flow again.'),
+      );
+    }
+
+    try {
+      return await this.finalizeCallback({
+        res,
+        locale,
+        ipAddress,
+        userAgent,
+        provider,
+        type: flow,
+        profile,
+        userId,
+        includeRefreshTokenInBody: false,
+      });
+    } catch (error) {
+      throw this.mapCallbackError(locale, provider, flow, error);
+    }
+  }
+
   private async finalizeCallback({
     res,
     locale,

package/src/oauth/providers/microsoft-entra-id.provider.ts

@@ -35,10 +35,22 @@ export class MicrosoftEntraIdProvider extends BaseOAuthProvider {
     return 'MICROSOFT-ENTRA-ID';
   }
 
+  // Fixed API callback used by the web flow so the ~2KB Entra `code` is received
+  // and exchanged server-side (never forwarded into a front-end app URL).
+  private static readonly API_CALLBACK_PATH = '/oauth/microsoft-entra-id/callback';
+
+  // Apps whose front-end callback pages know how to redeem the server-side bounce
+  // `ref`. Only these use the API bounce; every other web app (and mobile) keeps the
+  // legacy front-end redirect, so this change is additive and non-regressing. Add an
+  // app here once its callback pages handle `?ref=`. `self` is the hub (admin), which
+  // initiates Entra without a `redirectApp` and thus resolves to the sentinel `self`.
+  private static readonly API_BOUNCE_APPS = new Set(['class', 'self', 'training', 'partners']);
+
   private async loadConfig() {
     const settings = await this.setting.getSettingValues([
       'oauth-microsoft-entra-id-profile-id',
       'url',
+      'api-url',
     ]);
     const profileSlug = String(settings['oauth-microsoft-entra-id-profile-id'] ?? '').trim();
     if (!profileSlug) throw new BadRequestException('Microsoft Entra ID OAuth profile not configured.');
@@ -56,19 +68,47 @@ export class MicrosoftEntraIdProvider extends BaseOAuthProvider {
     if (!tenantId) {
       throw new BadRequestException('Microsoft Entra ID OAuth profile is missing tenant_id.');
     }
-    return { clientId, clientSecret, tenantId, baseUrl: String(settings['url'] ?? '') };
+    return {
+      clientId,
+      clientSecret,
+      tenantId,
+      baseUrl: String(settings['url'] ?? ''),
+      apiUrl: String(settings['api-url'] ?? ''),
+    };
   }
 
-  async getAuthUrl(callbackPath: string) {
-    const { clientId, tenantId, baseUrl } = await this.loadConfig();
+  /** Absolute redirect URI the web flow registers/exchanges against (the API). */
+  private buildApiRedirectUri(apiUrl: string) {
+    if (!String(apiUrl).trim()) {
+      throw new BadRequestException(
+        'Microsoft Entra ID OAuth requires the `api-url` setting for the web callback.',
+      );
+    }
+    return this.buildRedirectUri(apiUrl, MicrosoftEntraIdProvider.API_CALLBACK_PATH);
+  }
+
+  async getAuthUrl(
+    callbackPath: string,
+    flow?: 'login' | 'register' | 'connect',
+    app?: string,
+  ) {
+    const { clientId, tenantId, baseUrl, apiUrl } = await this.loadConfig();
     const settings = await this.setting.getSettingValues(['oauth-microsoft-entra-id-scopes']);
     const baseScopes: string[] = settings['oauth-microsoft-entra-id-scopes'] ?? ['openid', 'profile', 'email'];
     const scopes = baseScopes.includes('offline_access')
       ? baseScopes
       : [...baseScopes, 'offline_access'];
 
-    const redirectURI = this.buildRedirectUri(baseUrl, callbackPath);
-    const isConnectFlow = callbackPath.includes('/connect');
+    // Only apps that can redeem a `ref` bounce through the API (where the ~2KB code
+    // is exchanged server-side); every other web app and mobile keep the front-end
+    // callback, so this stays additive and non-regressing.
+    const useApiBounce = !!app && MicrosoftEntraIdProvider.API_BOUNCE_APPS.has(app);
+    const redirectURI = useApiBounce
+      ? this.buildApiRedirectUri(apiUrl)
+      : this.buildRedirectUri(baseUrl, callbackPath);
+    const isConnectFlow = useApiBounce
+      ? flow === 'connect'
+      : callbackPath.includes('/connect');
     const params = new URLSearchParams({
       client_id: clientId,
       redirect_uri: redirectURI,

package/src/profile/profile.controller.ts

@@ -2,6 +2,10 @@ import { NoRole, User } from '@hed-hog/api';
 import { Locale } from '@hed-hog/api-locale';
 import { Body, Controller, Delete, Get, Headers, Ip, Param, ParseIntPipe, Post, Put, UploadedFile, UseInterceptors } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
+import type {
+    PublicKeyCredentialCreationOptionsJSON,
+    PublicKeyCredentialRequestOptionsJSON,
+} from '@simplewebauthn/server';
 import { ChangeEmailDto } from './dto/change-email.dto';
 import { ChangePasswordDto } from './dto/change-password.dto';
 import { EmailVerificationDto } from './dto/email-verification-confirm.dto';
@@ -161,7 +165,7 @@ export class ProfileController {
     @Body() { name }: GenerateWebAuthnRegistrationOptionsDto,
     @Locale() locale: string,
     @Headers('origin') origin: string
-  ) {
+  ): Promise<PublicKeyCredentialCreationOptionsJSON> {
     return this.profileService.generateWebAuthnRegistrationOptions(locale, id, name, origin);
   }
 
@@ -180,7 +184,7 @@ export class ProfileController {
     @User() { id },
     @Locale() locale: string,
     @Headers('origin') origin: string
-  ) {
+  ): Promise<PublicKeyCredentialRequestOptionsJSON> {
     return this.profileService.generateWebAuthnAuthenticationOptions(locale, id, origin);
   }
 

package/src/profile/profile.service.ts

@@ -5,6 +5,8 @@ import { BadRequestException, forwardRef, Inject, Injectable, NotFoundException
 import { EventEmitter2 } from '@nestjs/event-emitter';
 import { JwtService } from '@nestjs/jwt';
 import type {
+    PublicKeyCredentialCreationOptionsJSON,
+    PublicKeyCredentialRequestOptionsJSON,
     VerifiedAuthenticationResponse,
     VerifiedRegistrationResponse,
 } from '@simplewebauthn/server';
@@ -1221,7 +1223,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnRegistrationOptions(locale: string, userId: number, name: string, requestOrigin?: string) {
+  async generateWebAuthnRegistrationOptions(locale: string, userId: number, name: string, requestOrigin?: string): Promise<PublicKeyCredentialCreationOptionsJSON> {
     try {
       const user = await this.prisma.user.findFirst({
         where: { id: userId },
@@ -1367,7 +1369,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnAuthenticationOptions(locale: string, userId: number, requestOrigin?: string) {
+  async generateWebAuthnAuthenticationOptions(locale: string, userId: number, requestOrigin?: string): Promise<PublicKeyCredentialRequestOptionsJSON> {
     try {
       const user = await this.prisma.user.findFirst({
         where: { id: userId },
@@ -1500,7 +1502,7 @@ export class ProfileService {
     }
   }
 
-  async generateWebAuthnAuthenticationOptionsForLogin(locale: string, mfaToken: string) {
+  async generateWebAuthnAuthenticationOptionsForLogin(locale: string, mfaToken: string): Promise<PublicKeyCredentialRequestOptionsJSON> {
     try {
       const decoded = this.jwt.decode(mfaToken) as any;
       if (!decoded || !decoded.userId) {

package/src/webhook-integration/webhook-integration.controller.ts

@@ -15,6 +15,7 @@ import {
   Res,
 } from '@nestjs/common';
 import { Request, Response } from 'express';
+import { WebhookProtocolResponse } from './webhook-protocol.registry';
 import { WebhookIntegrationService } from './webhook-integration.service';
 import {
   CreateWebhookActionDTO,
@@ -145,12 +146,24 @@ export class PublicWebhookController {
   constructor(private readonly service: WebhookIntegrationService) {}
 
   @Post(':uuid')
-  execute(
+  async execute(
     @Param('uuid') uuid: string,
     @Body() body: any,
+    @Query() query: any,
     @Headers() headers: any,
     @Req() req: Request,
+    @Res({ passthrough: true }) res: Response,
   ) {
+    const handled = await this.service.executeProtocol(
+      uuid,
+      'POST',
+      body,
+      query,
+      headers,
+      req,
+    );
+    if (handled) return sendProtocolResponse(res, handled);
+
     return this.service.executePublic(uuid, body, headers, req);
   }
 
@@ -158,15 +171,40 @@ export class PublicWebhookController {
    * GET variant so a webhook can be triggered by a plain clickable link (e.g.
    * approve/reject links sent by email/WhatsApp). Query params are used as the
    * payload for action templates (`{{body.decision}}` ← `?decision=approve`).
+   *
+   * Webhooks with a protocol take a different path: for them a GET is the
+   * provider's verification handshake, not a trigger — it must not run actions.
    */
   @Get(':uuid')
-  executeGet(
+  async executeGet(
     @Param('uuid') uuid: string,
     @Query() query: any,
     @Headers() headers: any,
     @Req() req: Request,
+    @Res({ passthrough: true }) res: Response,
   ) {
+    const handled = await this.service.executeProtocol(
+      uuid,
+      'GET',
+      query ?? {},
+      query,
+      headers,
+      req,
+    );
+    if (handled) return sendProtocolResponse(res, handled);
+
     return this.service.executePublic(uuid, query ?? {}, headers, req);
   }
 }
 
+/**
+ * Aplica status/content-type que o adaptador pediu. Devolver a string crua importa:
+ * provedores como a Meta comparam o corpo da resposta literalmente, então um
+ * envelope JSON reprovaria a verificação.
+ */
+function sendProtocolResponse(res: Response, result: WebhookProtocolResponse) {
+  res.status(result.status);
+  if (result.contentType) res.type(result.contentType);
+  return result.body;
+}
+

package/src/webhook-integration/webhook-integration.module.ts

@@ -16,6 +16,7 @@ import {
   WebhookIntegrationController,
 } from './webhook-integration.controller';
 import { WebhookIntegrationService } from './webhook-integration.service';
+import { WebhookProtocolRegistry } from './webhook-protocol.registry';
 
 @Module({
   imports: [
@@ -38,12 +39,16 @@ import { WebhookIntegrationService } from './webhook-integration.service';
     IntegrationEventCatalogService,
     WebhookIntegrationService,
     EventWebhookService,
+    WebhookProtocolRegistry,
   ],
   exports: [
     IntegrationEventCatalogService,
     AppCommandModule,
     WebhookIntegrationService,
     EventWebhookService,
+    // Exportado para que outros módulos registrem protocolos de entrada
+    // (ex.: a library whatsapp registra o protocolo da Meta).
+    WebhookProtocolRegistry,
   ],
 })
 export class WebhookIntegrationModule {}

package/src/webhook-integration/webhook-integration.service.ts

@@ -7,6 +7,7 @@ import {
     BadRequestException,
     HttpException,
     Injectable,
+    Logger,
     NotFoundException,
 } from '@nestjs/common';
 import { EventEmitter } from 'events';
@@ -25,6 +26,11 @@ import {
     UpdateWebhookActionDTO,
 } from './dto/webhook-action.dto';
 import { AppCommandRegistry } from '../app-command/app-command.registry';
+import {
+    WebhookProtocolRegistry,
+    WebhookProtocolRequest,
+    WebhookProtocolResponse,
+} from './webhook-protocol.registry';
 import {
     createPlainToken,
     createPublicUuid,
@@ -58,6 +64,7 @@ type WebhookActionPayload =
 
 @Injectable()
 export class WebhookIntegrationService {
+  private readonly logger = new Logger(WebhookIntegrationService.name);
   private readonly logEmitter = new EventEmitter();
   private readonly webhookActionSelect = {
     id: true,
@@ -105,6 +112,7 @@ export class WebhookIntegrationService {
     private readonly settingService: SettingService,
     private readonly commandRegistry: AppCommandRegistry,
     private readonly mcpApiKeyService: McpApiKeyService,
+    private readonly protocolRegistry: WebhookProtocolRegistry,
   ) {}
 
   private get integrations() {
@@ -551,6 +559,131 @@ export class WebhookIntegrationService {
     });
   }
 
+  /**
+   * Cria (ou devolve) o webhook de um perfil de integração que fala um protocolo
+   * próprio. Idempotente: a chave é (protocol, integration_profile_id), então
+   * chamar de novo devolve o mesmo UUID — e a URL já registrada no painel do
+   * provedor continua válida.
+   *
+   * Existe para que módulos não precisem montar a URL pública por conta própria:
+   * `/webhook/:uuid` e a base vinda dos settings ficam sob responsabilidade do core.
+   */
+  async provisionProtocolWebhook(input: {
+    slug: string;
+    name: string;
+    protocol: string;
+    integrationProfileId: number;
+    description?: string;
+  }) {
+    const existing = await this.integrations.findFirst({
+      where: {
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+      },
+    });
+
+    if (existing) return this.withPublicUrl(existing);
+
+    const created = await this.integrations.create({
+      data: {
+        slug: await this.ensureProvisionSlug(input.slug),
+        name: input.name,
+        description: input.description ?? null,
+        protocol: input.protocol,
+        integration_profile_id: input.integrationProfileId,
+        public_uuid: createPublicUuid(),
+        status: 'active',
+        // Webhooks de protocolo não usam o token estático do core: o adaptador
+        // faz a própria autenticação (HMAC, no caso da Meta).
+        require_token: false,
+      },
+    });
+
+    this.logger.log(
+      `Provisioned "${input.protocol}" webhook ${created.id} for integration profile ${input.integrationProfileId}`,
+    );
+
+    return this.withPublicUrl(created);
+  }
+
+  /** Sufixa o slug até achar um livre (o slug é unique na tabela). */
+  private async ensureProvisionSlug(base: string): Promise<string> {
+    const slug = base.trim();
+    if (!(await this.integrations.findUnique({ where: { slug } }))) return slug;
+
+    for (let i = 2; ; i++) {
+      const candidate = `${slug}-${i}`;
+      if (!(await this.integrations.findUnique({ where: { slug: candidate } }))) {
+        return candidate;
+      }
+    }
+  }
+
+  /**
+   * Entrega a chamada ao adaptador de protocolo do webhook, se houver um.
+   *
+   * Devolve `null` quando o webhook é clássico (protocol nulo) ou quando nenhum
+   * módulo registrou o protocolo — nesse caso o chamador segue pelo fluxo normal
+   * de token + actions.
+   *
+   * Webhooks com protocolo NÃO passam por validateToken/validateIp/validateBodySchema:
+   * o adaptador faz a própria autenticação (a Meta, por exemplo, assina com HMAC).
+   */
+  async executeProtocol(
+    uuid: string,
+    method: 'GET' | 'POST',
+    body: any,
+    query: any,
+    headers: any,
+    req: Request,
+  ): Promise<WebhookProtocolResponse | null> {
+    const integration = await this.integrations.findUnique({
+      where: { public_uuid: uuid },
+      select: {
+        id: true,
+        slug: true,
+        status: true,
+        protocol: true,
+        integration_profile_id: true,
+      },
+    });
+
+    if (!integration?.protocol) return null;
+
+    const adapter = this.protocolRegistry.get(integration.protocol);
+    if (!adapter) {
+      // Protocolo gravado mas nenhum módulo o registrou (library desabilitada,
+      // por exemplo). Não cai no fluxo de actions: seria autenticar com o token
+      // clássico um webhook que deveria exigir a auth do provedor.
+      this.logger.error(
+        `Webhook ${integration.id} declares protocol "${integration.protocol}", but no adapter is registered.`,
+      );
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    if (integration.status !== 'active') {
+      throw new NotFoundException('Webhook not found.');
+    }
+
+    const request: WebhookProtocolRequest = {
+      integration: {
+        id: integration.id,
+        slug: integration.slug,
+        integration_profile_id: integration.integration_profile_id ?? null,
+      },
+      body,
+      query: (query ?? {}) as Record<string, string>,
+      headers: (headers ?? {}) as Record<string, string | string[] | undefined>,
+      rawBody: (req as Request & { rawBody?: Buffer }).rawBody,
+      remoteIp: this.getRemoteIp(req),
+      req,
+    };
+
+    return method === 'GET'
+      ? adapter.verify(request)
+      : adapter.handle(request);
+  }
+
   async executePublic(uuid: string, body: any, headers: any, req: Request) {
     const startedAt = Date.now();
     const remoteIp = this.getRemoteIp(req);
@@ -610,6 +743,10 @@ export class WebhookIntegrationService {
       body,
       remoteIp,
       webhookHeaders: normalizeJsonObject(headers) || {},
+      // `rawBody` is stashed onto the request by the API's global body-parser `verify`
+      // callback (apps/api/src/main.ts); typed loosely here since this package doesn't
+      // own that Express.Request augmentation.
+      webhookRawBody: (req as Request & { rawBody?: Buffer }).rawBody,
       startedAt,
     });
   }
@@ -625,10 +762,18 @@ export class WebhookIntegrationService {
     body: any;
     remoteIp: string | null;
     webhookHeaders: Record<string, unknown>;
+    webhookRawBody?: Buffer;
     startedAt: number;
   }) {
-    const { integration, uuid, body, remoteIp, webhookHeaders, startedAt } =
-      input;
+    const {
+      integration,
+      uuid,
+      body,
+      remoteIp,
+      webhookHeaders,
+      webhookRawBody,
+      startedAt,
+    } = input;
     const actionLogs: ActionExecutionLog[] = [];
 
     try {
@@ -639,6 +784,7 @@ export class WebhookIntegrationService {
         try {
           const result = await this.executeAction(action, body, {
             webhookHeaders,
+            webhookRawBody,
             remoteIp,
             publicUuid: uuid,
             integrationId: integration.id,
@@ -811,6 +957,7 @@ export class WebhookIntegrationService {
     body: any,
     context?: {
       webhookHeaders?: Record<string, unknown>;
+      webhookRawBody?: Buffer;
       remoteIp?: string | null;
       publicUuid?: string;
       integrationId?: number;
@@ -1138,6 +1285,7 @@ export class WebhookIntegrationService {
     body: any,
     context?: {
       webhookHeaders?: Record<string, unknown>;
+      webhookRawBody?: Buffer;
       remoteIp?: string | null;
       publicUuid?: string;
       integrationId?: number;
@@ -1172,6 +1320,7 @@ export class WebhookIntegrationService {
       result = await this.commandRegistry.dispatch(slug, renderedParams, {
         webhookBody: body,
         webhookHeaders: context?.webhookHeaders,
+        webhookRawBody: context?.webhookRawBody,
         remoteIp: context?.remoteIp,
         publicUuid: context?.publicUuid,
         integrationId: context?.integrationId,