@shipfox/api-integration-sentry 5.0.0 → 6.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-sentry",
   "license": "MIT",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -26,14 +26,14 @@
     "drizzle-orm": "^0.45.2",
     "ky": "^2.0.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "5.0.0",
-    "@shipfox/api-integration-core-dto": "5.0.0",
+    "@shipfox/api-auth-context": "6.0.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-integration-sentry-dto": "6.0.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-drizzle": "0.3.1",
-    "@shipfox/api-integration-sentry-dto": "5.0.0",
-    "@shipfox/node-module": "0.3.2",
+    "@shipfox/node-drizzle": "0.3.2",
+    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-module": "0.4.0",
     "@shipfox/node-opentelemetry": "0.5.2",
-    "@shipfox/node-fastify": "0.2.3",
     "@shipfox/node-postgres": "0.4.2"
   },
   "devDependencies": {
@@ -43,16 +43,18 @@
     "fastify-type-provider-zod": "^6.0.0",
     "fishery": "^2.4.0",
     "@shipfox/biome": "1.8.2",
-    "@shipfox/node-temporal": "0.3.1",
+    "@shipfox/depcruise": "1.0.2",
+    "@shipfox/node-temporal": "0.3.2",
     "@shipfox/swc": "1.2.6",
     "@shipfox/ts-config": "1.3.8",
-    "@shipfox/vitest": "1.2.3",
-    "@shipfox/typescript": "1.1.7"
+    "@shipfox/typescript": "1.1.7",
+    "@shipfox/vitest": "1.2.3"
   },
   "scripts": {
     "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
+    "depcruise": "shipfox-depcruise",
     "test": "shipfox-vitest-run",
     "test:watch": "shipfox-vitest-watch",
     "type": "shipfox-tsc-check",

package/src/config.ts

@@ -15,15 +15,14 @@ export const config = createConfig({
     default: true,
   }),
   SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS: num({
-    desc: 'How many days a verified-but-unclaimed Sentry installation may sit before the daily cleanup cron tombstones it. Must be at least 1; a smaller value moves the cutoff to now or the future and would tombstone freshly created, still-unclaimed installs. A reinstall always mints a fresh uuid, so a tombstone is never revived. Defaults to 7.',
+    desc: 'How many days an unclaimed Sentry installation or incomplete exchange may sit without a state transition. The daily cleanup releases pending claims and tombstones verified installs after this window. Must be at least 1. Defaults to 7.',
     default: 7,
   }),
 });
 
-// The daily cleanup cron tombstones every unclaimed install older than
-// `now - SENTRY_UNCLAIMED_INSTALLATION_RETENTION_DAYS`. A value below 1 moves that
-// cutoff to now or the future, which would wipe freshly created installs nobody has
-// claimed yet. Reject it at startup rather than let the 04:00 cron fail silently.
+// A value below 1 moves the cutoff to now or the future, which would expire fresh
+// claims before a browser can bind them. Reject it at startup rather than let the
+// 04:00 cron fail silently.
 export function assertRetentionDaysWithinBounds(days: number): void {
   if (!Number.isFinite(days) || days < 1) {
     throw new Error(

package/src/core/install.ts

@@ -89,7 +89,7 @@ export async function verifyAndPersistUnclaimedInstallation(
   });
 
   if (params.verifyInstall) {
-    await bestEffortVerifyInstallation({
+    await verifySentryInstallationBestEffort({
       sentry: params.sentry,
       installationUuid: params.installationUuid,
       token: authorization.token,
@@ -143,6 +143,9 @@ export async function handleSentryConnect(
     if (install.connectionId) {
       return resolveClaimedInstall(params, install.connectionId);
     }
+    if (!isVerifiedUnclaimed(install)) {
+      throw new SentryVerificationInProgressError(params.installationUuid);
+    }
     return claimVerifiedInstall(params, install);
   }
 
@@ -162,7 +165,7 @@ async function resolveClaimedInstall(
 
 async function claimVerifiedInstall(
   params: HandleSentryConnectParams,
-  install: SentryInstallation,
+  install: VerifiedUnclaimedSentryInstallation,
 ): Promise<IntegrationConnection<'sentry'>> {
   let authorization: SentryAuthorization;
   try {
@@ -188,7 +191,7 @@ async function claimVerifiedInstall(
     codeHash: hashAuthorizationCode(params.code),
   });
   if (params.verifyInstall) {
-    await bestEffortVerifyInstallation({
+    await verifySentryInstallationBestEffort({
       sentry: params.sentry,
       installationUuid: params.installationUuid,
       token: authorization.token,
@@ -222,7 +225,7 @@ async function claimBrowserFirst(
     codeHash: hashAuthorizationCode(params.code),
   });
   if (params.verifyInstall) {
-    await bestEffortVerifyInstallation({
+    await verifySentryInstallationBestEffort({
       sentry: params.sentry,
       installationUuid: params.installationUuid,
       token: result.authorization.token,
@@ -255,8 +258,19 @@ async function reconcileConcurrentClaim(
   throw new SentryVerificationInProgressError(params.installationUuid);
 }
 
-function isVerifiedUnclaimed(install: SentryInstallation): boolean {
-  return install.connectionId === null && install.status === 'installed';
+type VerifiedUnclaimedSentryInstallation = SentryInstallation & {
+  connectionId: null;
+  status: 'installed';
+  orgSlug: string;
+  codeHash: string;
+};
+
+function isVerifiedUnclaimed(
+  install: SentryInstallation,
+): install is VerifiedUnclaimedSentryInstallation {
+  return (
+    install.connectionId === null && install.status === 'installed' && install.codeHash !== null
+  );
 }
 
 function bindClaim(
@@ -273,7 +287,7 @@ function bindClaim(
   });
 }
 
-async function bestEffortVerifyInstallation(input: {
+export async function verifySentryInstallationBestEffort(input: {
   sentry: SentryApiClient;
   installationUuid: string;
   token: string;

package/src/core/signature.ts

@@ -1,7 +1,7 @@
 import {verifyHexHmacSignature} from '@shipfox/node-fastify';
 
 export interface VerifySentrySignatureParams {
-  rawBody: string;
+  rawBody: string | Uint8Array;
   signature: string;
   secret: string;
 }

package/src/core/webhook-processor.test.ts

@@ -0,0 +1,304 @@
+import {createHmac, randomUUID} from 'node:crypto';
+import {
+  createStoredWebhookRequest,
+  type IntegrationConnection,
+} from '@shipfox/api-integration-core-dto';
+import {eq} from 'drizzle-orm';
+import type {SentryApiClient} from '#api/client.js';
+import {db} from '#db/db.js';
+import {sentryInstallations} from '#db/schema/installations.js';
+import {sentryInstallationFactory, sentryIssueWebhookFactory} from '#test/index.js';
+import {createSentryWebhookProcessor} from './webhook-processor.js';
+
+const CLIENT_SECRET = 'test-client-secret';
+
+function fakeConnection(overrides: Partial<IntegrationConnection> = {}): IntegrationConnection {
+  return {
+    id: randomUUID(),
+    workspaceId: randomUUID(),
+    provider: 'sentry',
+    externalAccountId: 'install-uuid',
+    slug: 'sentry_acme',
+    displayName: 'Sentry acme',
+    lifecycleStatus: 'active',
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...overrides,
+  };
+}
+
+function sentryClient(overrides: Partial<SentryApiClient> = {}): SentryApiClient {
+  return {
+    exchangeAuthorizationCode: vi.fn(() =>
+      Promise.resolve({token: 'tok', refreshToken: 'refresh', expiresAt: 'x'}),
+    ),
+    getInstallation: vi.fn(() => Promise.resolve({orgSlug: 'acme'})),
+    verifyInstallation: vi.fn(() => Promise.resolve()),
+    ...overrides,
+  };
+}
+
+function signedRequest(input: {body: unknown; deliveryId?: string; resource: string}) {
+  const rawBody = Buffer.from(JSON.stringify(input.body));
+  const signature = createHmac('sha256', CLIENT_SECRET).update(rawBody).digest('hex');
+
+  return createStoredWebhookRequest({
+    requestId: randomUUID(),
+    routeId: 'sentry',
+    receivedAt: new Date().toISOString(),
+    rawQueryString: '',
+    headers: {
+      'content-type': 'application/json',
+      'request-id': input.deliveryId ?? randomUUID(),
+      'sentry-hook-resource': input.resource,
+      'sentry-hook-signature': signature,
+    },
+    body: rawBody,
+  });
+}
+
+describe('Sentry webhook processor', () => {
+  beforeEach(async () => {
+    await db().delete(sentryInstallations);
+  });
+
+  it('processes a valid issue delivery outside the HTTP adapter', async () => {
+    const connection = fakeConnection();
+    const installationUuid = 'processor-issue-installation';
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient(),
+      coreDb: db,
+      publishIntegrationEventReceived,
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(connection)),
+      updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+    });
+    await sentryInstallationFactory.create({installationUuid, connectionId: connection.id});
+    const request = signedRequest({
+      resource: 'issue',
+      body: sentryIssueWebhookFactory.build({
+        action: 'created',
+        installation: {uuid: installationUuid},
+      }),
+    });
+
+    const result = await processor.process(request);
+
+    expect(result).toMatchObject({outcome: 'processed'});
+    expect(publishIntegrationEventReceived).toHaveBeenCalledOnce();
+  });
+
+  it('processes an installation deletion outside the HTTP adapter', async () => {
+    const installationUuid = 'processor-installation-deletion';
+    const updateConnectionLifecycleStatus = vi.fn(() => Promise.resolve(undefined));
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient(),
+      coreDb: db,
+      publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(fakeConnection())),
+      updateConnectionLifecycleStatus,
+    });
+    const connectionId = randomUUID();
+    await sentryInstallationFactory.create({installationUuid, connectionId});
+    const request = signedRequest({
+      resource: 'installation',
+      body: {action: 'deleted', data: {installation: {uuid: installationUuid}}},
+    });
+
+    const result = await processor.process(request);
+
+    const [installation] = await db()
+      .select()
+      .from(sentryInstallations)
+      .where(eq(sentryInstallations.installationUuid, installationUuid));
+    expect(result).toMatchObject({outcome: 'processed'});
+    expect(installation?.status).toBe('deleted');
+    expect(updateConnectionLifecycleStatus).toHaveBeenCalledWith(
+      {id: connectionId, lifecycleStatus: 'disabled'},
+      expect.objectContaining({tx: expect.anything()}),
+    );
+  });
+
+  it('does not create a side effect for an invalid signature', async () => {
+    const publishIntegrationEventReceived = vi.fn(() => Promise.resolve({published: true}));
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient(),
+      coreDb: db,
+      publishIntegrationEventReceived,
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(fakeConnection())),
+      updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+    });
+    const request = signedRequest({
+      resource: 'issue',
+      body: sentryIssueWebhookFactory.build({action: 'created'}),
+    });
+    request.headers['sentry-hook-signature'] = 'not-a-signature';
+
+    const result = await processor.process(request);
+
+    expect(result).toMatchObject({outcome: 'discarded', reason: 'invalid_signature'});
+    expect(publishIntegrationEventReceived).not.toHaveBeenCalled();
+  });
+
+  it('continues from the durable exchange checkpoint after completion persistence fails', async () => {
+    const installationUuid = 'processor-installation-retry';
+    const deliveryId = randomUUID();
+    const exchangeAuthorizationCode = vi.fn(() =>
+      Promise.resolve({token: 'tok', refreshToken: 'refresh', expiresAt: 'x'}),
+    );
+    const recordDeliveryOnly = vi
+      .fn()
+      .mockRejectedValueOnce(new Error('delivery persistence failed'))
+      .mockResolvedValueOnce(undefined);
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient({exchangeAuthorizationCode}),
+      coreDb: db,
+      publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+      recordDeliveryOnly,
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(fakeConnection())),
+      updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+    });
+    const request = signedRequest({
+      deliveryId,
+      resource: 'installation',
+      body: {
+        action: 'created',
+        data: {
+          installation: {
+            uuid: installationUuid,
+            code: 'single-use-code',
+            organization: {slug: 'acme'},
+          },
+        },
+      },
+    });
+
+    const firstAttempt = processor.process(request);
+    await expect(firstAttempt).rejects.toThrow('delivery persistence failed');
+    const checkpoint = await db()
+      .select()
+      .from(sentryInstallations)
+      .where(eq(sentryInstallations.installationUuid, installationUuid));
+    const retryResult = await processor.process(request);
+    const [completed] = await db()
+      .select()
+      .from(sentryInstallations)
+      .where(eq(sentryInstallations.installationUuid, installationUuid));
+
+    expect(checkpoint[0]?.status).toBe('exchange-succeeded');
+    expect(retryResult).toEqual({outcome: 'processed', deliveryId});
+    expect(completed?.status).toBe('installed');
+    expect(exchangeAuthorizationCode).toHaveBeenCalledTimes(1);
+    expect(recordDeliveryOnly).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps deletion terminal when it races a pending installation exchange', async () => {
+    const installationUuid = 'processor-installation-delete-race';
+    let signalExchangeStarted = (): void => undefined;
+    const exchangeStarted = new Promise<void>((resolve) => {
+      signalExchangeStarted = resolve;
+    });
+    let finishExchange!: (authorization: {
+      token: string;
+      refreshToken: string;
+      expiresAt: string;
+    }) => void;
+    const exchangeResult = new Promise<{
+      token: string;
+      refreshToken: string;
+      expiresAt: string;
+    }>((resolve) => {
+      finishExchange = resolve;
+    });
+    const exchangeAuthorizationCode = vi.fn(() => {
+      signalExchangeStarted();
+      return exchangeResult;
+    });
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient({exchangeAuthorizationCode}),
+      coreDb: db,
+      publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(fakeConnection())),
+      updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+    });
+    const creation = signedRequest({
+      resource: 'installation',
+      body: {
+        action: 'created',
+        data: {
+          installation: {
+            uuid: installationUuid,
+            code: 'single-use-code',
+            organization: {slug: 'acme'},
+          },
+        },
+      },
+    });
+    const deletion = signedRequest({
+      resource: 'installation',
+      body: {action: 'deleted', data: {installation: {uuid: installationUuid}}},
+    });
+
+    const creationAttempt = processor.process(creation);
+    await exchangeStarted;
+    const deletionResult = await processor.process(deletion);
+    finishExchange({token: 'tok', refreshToken: 'refresh', expiresAt: 'x'});
+    const creationResult = await creationAttempt;
+    const [installation] = await db()
+      .select()
+      .from(sentryInstallations)
+      .where(eq(sentryInstallations.installationUuid, installationUuid));
+
+    expect(creationResult.outcome).toBe('processed');
+    expect(deletionResult.outcome).toBe('processed');
+    expect(installation?.status).toBe('deleted');
+  });
+
+  it('keeps an out-of-order deletion as a monotonic tombstone', async () => {
+    const installationUuid = 'processor-installation-reordered';
+    const exchangeAuthorizationCode = vi.fn(() =>
+      Promise.resolve({token: 'tok', refreshToken: 'refresh', expiresAt: 'x'}),
+    );
+    const processor = createSentryWebhookProcessor({
+      sentry: sentryClient({exchangeAuthorizationCode}),
+      coreDb: db,
+      publishIntegrationEventReceived: vi.fn(() => Promise.resolve({published: true})),
+      recordDeliveryOnly: vi.fn(() => Promise.resolve()),
+      getIntegrationConnectionById: vi.fn(() => Promise.resolve(fakeConnection())),
+      updateConnectionLifecycleStatus: vi.fn(() => Promise.resolve(undefined)),
+    });
+    const deletion = signedRequest({
+      resource: 'installation',
+      body: {action: 'deleted', data: {installation: {uuid: installationUuid}}},
+    });
+    const creation = signedRequest({
+      resource: 'installation',
+      body: {
+        action: 'created',
+        data: {
+          installation: {
+            uuid: installationUuid,
+            code: 'single-use-code',
+            organization: {slug: 'acme'},
+          },
+        },
+      },
+    });
+
+    const deletionResult = await processor.process(deletion);
+    const creationResult = await processor.process(creation);
+    const [installation] = await db()
+      .select()
+      .from(sentryInstallations)
+      .where(eq(sentryInstallations.installationUuid, installationUuid));
+
+    expect(deletionResult.outcome).toBe('processed');
+    expect(creationResult.outcome).toBe('processed');
+    expect(installation?.status).toBe('deleted');
+    expect(exchangeAuthorizationCode).not.toHaveBeenCalled();
+  });
+});

package/src/core/webhook-processor.ts

@@ -0,0 +1,224 @@
+import {Buffer} from 'node:buffer';
+import {
+  decodeWebhookBody,
+  type GetIntegrationConnectionByIdFn,
+  type PublishIntegrationEventReceivedFn,
+  type RecordDeliveryOnlyFn,
+  type StoredWebhookRequest,
+  type UpdateIntegrationConnectionLifecycleStatusFn,
+  type WebhookProcessingResult,
+} from '@shipfox/api-integration-core-dto';
+import {
+  sentryInstallationWebhookSchema,
+  sentryIssueWebhookSchema,
+} from '@shipfox/api-integration-sentry-dto';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import type {SentryApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {SentryIssueDroppedError} from '#core/errors.js';
+import {
+  handleSentryInstallationCreated,
+  handleSentryInstallationDeleted,
+  handleSentryIssueEvent,
+  normalizeSentryIssueAction,
+} from '#core/webhook.js';
+import {
+  completeSentryInstallationVerification,
+  getSentryInstallationByInstallationUuid,
+} from '#db/installations.js';
+import {verifySentrySignature} from './signature.js';
+
+const DELIVERY_ID_HEADER = 'request-id';
+const RESOURCE_HEADER = 'sentry-hook-resource';
+const SIGNATURE_HEADER = 'sentry-hook-signature';
+const LEGACY_SIGNATURE_HEADER = 'sentry-app-signature';
+const ISSUE_RESOURCE = 'issue';
+const INSTALLATION_RESOURCE = 'installation';
+const SENTRY_PROVIDER = 'sentry';
+
+export interface SentryWebhookProcessor {
+  process(request: StoredWebhookRequest): Promise<WebhookProcessingResult>;
+}
+
+export interface CreateSentryWebhookProcessorOptions {
+  sentry: SentryApiClient;
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+  updateConnectionLifecycleStatus: UpdateIntegrationConnectionLifecycleStatusFn;
+}
+
+export function createSentryWebhookProcessor(
+  context: CreateSentryWebhookProcessorOptions,
+): SentryWebhookProcessor {
+  return {process: (request) => processSentryWebhookRequest(context, request)};
+}
+
+async function processSentryWebhookRequest(
+  context: CreateSentryWebhookProcessorOptions,
+  request: StoredWebhookRequest,
+): Promise<WebhookProcessingResult> {
+  if (request.route_id !== 'sentry') {
+    throw new Error(`Sentry processor cannot process ${request.route_id} requests`);
+  }
+
+  const deliveryId = request.headers[DELIVERY_ID_HEADER];
+  const resource = request.headers[RESOURCE_HEADER];
+  const signature = request.headers[SIGNATURE_HEADER] ?? request.headers[LEGACY_SIGNATURE_HEADER];
+  if (!deliveryId || !resource || !signature) {
+    return {outcome: 'discarded', reason: 'missing_required_input'};
+  }
+
+  const rawBody = Buffer.from(decodeWebhookBody(request.body));
+  if (!verifySentrySignature({rawBody, signature, secret: config.SENTRY_APP_CLIENT_SECRET})) {
+    return {outcome: 'discarded', reason: 'invalid_signature', deliveryId};
+  }
+
+  logger().debug(
+    {
+      deliveryId,
+      signatureHeader: request.headers[SIGNATURE_HEADER]
+        ? SIGNATURE_HEADER
+        : LEGACY_SIGNATURE_HEADER,
+    },
+    'sentry webhook: signature verified',
+  );
+
+  if (resource === ISSUE_RESOURCE) return processIssueResource(context, deliveryId, rawBody);
+  if (resource === INSTALLATION_RESOURCE)
+    return processInstallationResource(context, deliveryId, rawBody);
+
+  await recordDeliveryOnly(context, deliveryId);
+  return {outcome: 'discarded', reason: 'unsupported_event', deliveryId};
+}
+
+async function processIssueResource(
+  context: CreateSentryWebhookProcessorOptions,
+  deliveryId: string,
+  rawBody: Uint8Array,
+): Promise<WebhookProcessingResult> {
+  const parsed = parsePayload(
+    sentryIssueWebhookSchema,
+    rawBody,
+    deliveryId,
+    normalizeSentryIssueAction,
+  );
+  if (!parsed.success) {
+    await recordDeliveryOnly(context, deliveryId);
+    return {outcome: 'discarded', reason: parsed.reason, deliveryId};
+  }
+  const payload = parsed.data;
+
+  try {
+    await context.coreDb().transaction(async (tx) => {
+      await handleSentryIssueEvent({
+        tx,
+        deliveryId,
+        payload,
+        publishIntegrationEventReceived: context.publishIntegrationEventReceived,
+        getIntegrationConnectionById: context.getIntegrationConnectionById,
+      });
+    });
+  } catch (error) {
+    if (!(error instanceof SentryIssueDroppedError)) throw error;
+
+    logger().warn({deliveryId, err: error}, `sentry webhook: ${error.message}, dropping`);
+    await recordDeliveryOnly(context, deliveryId);
+    return {outcome: 'discarded', reason: 'connection_unavailable', deliveryId};
+  }
+
+  return {outcome: 'processed', deliveryId};
+}
+
+async function processInstallationResource(
+  context: CreateSentryWebhookProcessorOptions,
+  deliveryId: string,
+  rawBody: Uint8Array,
+): Promise<WebhookProcessingResult> {
+  const parsed = parsePayload(sentryInstallationWebhookSchema, rawBody, deliveryId);
+  if (!parsed.success) {
+    await recordDeliveryOnly(context, deliveryId);
+    return {outcome: 'discarded', reason: parsed.reason, deliveryId};
+  }
+  const payload = parsed.data;
+
+  const installation = payload.data.installation;
+  if (payload.action === 'deleted') {
+    await context.coreDb().transaction(async (tx) => {
+      await handleSentryInstallationDeleted({
+        tx,
+        deliveryId,
+        installationUuid: installation.uuid,
+        recordDeliveryOnly: context.recordDeliveryOnly,
+        updateConnectionLifecycleStatus: context.updateConnectionLifecycleStatus,
+      });
+    });
+    return {outcome: 'processed', deliveryId};
+  }
+
+  await handleSentryInstallationCreated({
+    deliveryId,
+    installationUuid: installation.uuid,
+    orgSlug: installation.organization?.slug,
+    code: installation.code,
+    sentry: context.sentry,
+    verifyInstall: config.SENTRY_APP_VERIFY_INSTALL,
+    getSentryInstallation: ({installationUuid}) =>
+      getSentryInstallationByInstallationUuid(installationUuid),
+    persistUnclaimedAndRecordDelivery: ({installationUuid, codeHash, deliveryId: id}) =>
+      context.coreDb().transaction(async (tx) => {
+        const completed = await completeSentryInstallationVerification(
+          {installationUuid, codeHash},
+          {tx},
+        );
+        await context.recordDeliveryOnly({tx, provider: SENTRY_PROVIDER, deliveryId: id});
+        if (completed) return completed;
+
+        const current = await getSentryInstallationByInstallationUuid(installationUuid, {tx});
+        if (!current) throw new Error('Sentry installation verification lost its claim');
+        return current;
+      }),
+    recordDelivery: (id) => recordDeliveryOnly(context, id),
+  });
+
+  return {outcome: 'processed', deliveryId};
+}
+
+type ParsePayloadResult<T> =
+  | {success: true; data: T}
+  | {success: false; reason: 'malformed_payload' | 'unsupported_event'};
+
+function parsePayload<T>(
+  schema: {safeParse(value: unknown): {success: true; data: T} | {success: false; error: unknown}},
+  rawBody: Uint8Array,
+  deliveryId: string,
+  normalize: (payload: unknown) => unknown = (payload) => payload,
+): ParsePayloadResult<T> {
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(Buffer.from(rawBody).toString('utf8'));
+  } catch (error) {
+    logger().warn({deliveryId, err: error}, 'sentry webhook: payload JSON parse failed, dropping');
+    return {success: false, reason: 'malformed_payload'};
+  }
+
+  const payload = schema.safeParse(normalize(parsedJson));
+  if (payload.success) return {success: true, data: payload.data};
+
+  logger().warn(
+    {deliveryId, issues: payload.error},
+    'sentry webhook: payload failed validation, dropping',
+  );
+  return {success: false, reason: 'unsupported_event'};
+}
+
+async function recordDeliveryOnly(
+  context: CreateSentryWebhookProcessorOptions,
+  deliveryId: string,
+): Promise<void> {
+  await context.coreDb().transaction(async (tx) => {
+    await context.recordDeliveryOnly({tx, provider: SENTRY_PROVIDER, deliveryId});
+  });
+}