@shipfox/api-integration-jira 12.2.0 → 12.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-jira",
   "license": "MIT",
-  "version": "12.2.0",
+  "version": "12.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -28,7 +28,7 @@
     "ky": "^2.0.0",
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.2.0",
-    "@shipfox/api-integration-spi": "1.0.1",
+    "@shipfox/api-integration-spi": "1.1.0",
     "@shipfox/api-integration-jira-dto": "12.2.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",

package/src/api/client.test.ts

@@ -5,6 +5,7 @@ import {mapJiraError} from './client.js';
 const mocks = vi.hoisted(() => ({
   delete: vi.fn(),
   post: vi.fn(),
+  put: vi.fn(),
   request: vi.fn(),
   warn: vi.fn(),
 }));
@@ -31,7 +32,11 @@ vi.mock('ky', () => {
     }
   }
   return {
-    default: Object.assign(mocks.request, {delete: mocks.delete, post: mocks.post}),
+    default: Object.assign(mocks.request, {
+      delete: mocks.delete,
+      post: mocks.post,
+      put: mocks.put,
+    }),
     HTTPError: MockHTTPError,
     TimeoutError: MockTimeoutError,
   };
@@ -80,18 +85,22 @@ describe('mapJiraError', () => {
 });
 
 function resolves(data: unknown) {
-  return {json: () => Promise.resolve(data)};
+  return {
+    json: () => Promise.resolve(data),
+    text: () => Promise.resolve(data === undefined ? '' : JSON.stringify(data)),
+  };
 }
 
 describe('Jira dynamic webhook API', () => {
   beforeEach(() => {
     mocks.delete.mockReset();
     mocks.post.mockReset();
+    mocks.put.mockReset();
     mocks.request.mockReset();
     mocks.warn.mockReset();
   });
 
-  it('registers the six curated events with the access token', async () => {
+  it('sends the six curated events with the configured JQL filter', async () => {
     mocks.post.mockReturnValue(
       resolves({webhookRegistrationResult: [{createdWebhookId: 123, errors: []}]}),
     );
@@ -121,7 +130,7 @@ describe('Jira dynamic webhook API', () => {
             'comment_updated',
             'comment_deleted',
           ],
-          jqlFilter: '',
+          jqlFilter: 'project != null',
         },
       ],
     });
@@ -322,6 +331,76 @@ describe('Jira dynamic webhook API', () => {
       }),
     );
   });
+
+  it('refreshes dynamic webhooks and returns the provider expiration date', async () => {
+    const expirationDate = '2030-01-31T00:00:00.000Z';
+    mocks.put.mockReturnValue(resolves({expirationDate}));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().refreshDynamicWebhooks({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        webhookIds: [123, 456],
+      }),
+    ).resolves.toEqual(new Date(expirationDate));
+
+    expect(mocks.put).toHaveBeenCalledWith(
+      'http://127.0.0.1:0/ex/jira/cloud-1/rest/api/3/webhook/refresh',
+      expect.objectContaining({
+        headers: {authorization: 'Bearer access-token'},
+        json: {webhookIds: [123, 456]},
+      }),
+    );
+  });
+
+  it.each([
+    {},
+    null,
+    undefined,
+  ])('returns undefined for an empty refresh response: %j', async (response) => {
+    mocks.put.mockReturnValue(resolves(response));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().refreshDynamicWebhooks({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        webhookIds: [123],
+      }),
+    ).resolves.toBeUndefined();
+  });
+
+  it.each([
+    [],
+    'malformed',
+    42,
+    false,
+  ])('rejects a non-object refresh response: %j', async (response) => {
+    mocks.put.mockReturnValue(resolves(response));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().refreshDynamicWebhooks({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        webhookIds: [123],
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+
+  it.each([400, 404])('treats refresh HTTP %i as a signal to re-register', async (status) => {
+    mocks.put.mockImplementation(rejectedRequest(status));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().refreshDynamicWebhooks({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        webhookIds: [123],
+      }),
+    ).resolves.toBeUndefined();
+  });
 });
 
 describe('Jira agent-tools REST API', () => {

package/src/api/client.ts

@@ -8,7 +8,8 @@ const JIRA_API_TIMEOUT_MS = 10_000;
 const SCOPE_SEPARATOR_RE = /[,\s]+/;
 const TRAILING_SLASHES_RE = /\/+$/;
 export const JIRA_DYNAMIC_WEBHOOK_EVENTS = jiraWebhookEventNames;
-export const JIRA_DYNAMIC_WEBHOOK_JQL = '';
+// Jira rejects an empty dynamic-webhook filter; every issue belongs to a project.
+export const JIRA_DYNAMIC_WEBHOOK_JQL = 'project != null';
 
 export interface JiraAuthorization {
   accessToken: string;
@@ -70,6 +71,16 @@ export interface JiraApiClient {
     cloudId: string;
     url: string;
   }): Promise<JiraDynamicWebhookRegistration>;
+  refreshDynamicWebhooks(input: {
+    accessToken: string;
+    cloudId: string;
+    webhookIds: number[];
+  }): Promise<Date | undefined>;
+  deleteDynamicWebhooks(input: {
+    accessToken: string;
+    cloudId: string;
+    webhookIds: number[];
+  }): Promise<void>;
   deleteDynamicWebhook(input: {
     accessToken: string;
     cloudId: string;
@@ -102,6 +113,16 @@ interface JiraDynamicWebhookRegistrationResponse {
 const JIRA_REFRESH_TOKEN_TERMINAL_ERROR_CODES = new Set(['invalid_grant', 'unauthorized_client']);
 
 export function createJiraApiClient(): JiraApiClient {
+  const deleteDynamicWebhooks: JiraApiClient['deleteDynamicWebhooks'] = async (input) => {
+    await mapJiraError('delete-dynamic-webhooks', () =>
+      ky.delete(`${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook`, {
+        headers: {authorization: `Bearer ${input.accessToken}`},
+        json: {webhookIds: input.webhookIds},
+        timeout: JIRA_API_TIMEOUT_MS,
+      }),
+    );
+  };
+
   return {
     async exchangeAuthorizationCode(input) {
       const body = await mapJiraError('exchange-authorization-code', () =>
@@ -189,14 +210,38 @@ export function createJiraApiClient(): JiraApiClient {
       return parseDynamicWebhookRegistration(body);
     },
 
+    async refreshDynamicWebhooks(input) {
+      const response = await mapJiraError('refresh-dynamic-webhooks', async () => {
+        try {
+          return await ky.put(
+            `${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook/refresh`,
+            {
+              headers: {authorization: `Bearer ${input.accessToken}`},
+              json: {webhookIds: input.webhookIds},
+              timeout: JIRA_API_TIMEOUT_MS,
+            },
+          );
+        } catch (error) {
+          if (
+            error instanceof HTTPError &&
+            (error.response.status === 400 || error.response.status === 404)
+          )
+            return undefined;
+          throw error;
+        }
+      });
+      if (!response) return undefined;
+      return parseDynamicWebhookExpiration(await readJiraResponseBody(response));
+    },
+
+    deleteDynamicWebhooks,
+
     async deleteDynamicWebhook(input) {
-      await mapJiraError('delete-dynamic-webhook', () =>
-        ky.delete(`${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook`, {
-          headers: {authorization: `Bearer ${input.accessToken}`},
-          json: {webhookIds: [input.webhookId]},
-          timeout: JIRA_API_TIMEOUT_MS,
-        }),
-      );
+      await deleteDynamicWebhooks({
+        accessToken: input.accessToken,
+        cloudId: input.cloudId,
+        webhookIds: [input.webhookId],
+      });
     },
   };
 }
@@ -309,6 +354,23 @@ function parseDynamicWebhookRegistration(
   return {webhookId: createdWebhookId};
 }
 
+function parseDynamicWebhookExpiration(body: unknown): Date | undefined {
+  if (body === undefined || body === null) return undefined;
+  if (typeof body !== 'object' || Array.isArray(body)) {
+    throw malformed('Jira webhook refresh response was malformed');
+  }
+  const expirationDate = (body as {expirationDate?: unknown}).expirationDate;
+  if (expirationDate === undefined) return undefined;
+  if (typeof expirationDate !== 'string') {
+    throw malformed('Jira webhook refresh response included a malformed expiration date');
+  }
+  const parsed = new Date(expirationDate);
+  if (Number.isNaN(parsed.getTime())) {
+    throw malformed('Jira webhook refresh response included a malformed expiration date');
+  }
+  return parsed;
+}
+
 function parseAuthorization(body: JiraTokenResponse): JiraAuthorization {
   if (typeof body.access_token !== 'string' || body.access_token.length === 0) {
     throw malformed('Jira authorization response did not include an access token');

package/src/core/disconnect.test.ts

@@ -1,8 +1,12 @@
+const {getInstallation} = vi.hoisted(() => ({getInstallation: vi.fn()}));
+
 vi.mock('#db/installations.js', () => ({
   deleteJiraInstallationByConnectionId: vi.fn().mockResolvedValue(true),
+  getJiraInstallationByConnectionId: getInstallation,
 }));
 
-import {disconnectJiraInstallation} from './disconnect.js';
+import type {JiraInstallation} from '#db/installations.js';
+import {deregisterJiraWebhooks, disconnectJiraInstallation} from './disconnect.js';
 
 describe('disconnectJiraInstallation', () => {
   it('deletes secrets, installation, and connection when the connection exists', async () => {
@@ -21,4 +25,106 @@ describe('disconnectJiraInstallation', () => {
     expect(deleteSecrets).toHaveBeenCalledOnce();
     expect(deleteConnection).toHaveBeenCalledOnce();
   });
+
+  it('deregisters webhooks before deletion and continues when the hook fails', async () => {
+    const deleteSecrets = vi.fn().mockResolvedValue(1);
+    const deleteConnection = vi.fn().mockResolvedValue(true);
+    const deregisterWebhooks = vi.fn().mockRejectedValue(new Error('Jira unavailable'));
+    const transaction = vi.fn(async (fn) => await fn({}));
+
+    await disconnectJiraInstallation({
+      connectionId: crypto.randomUUID(),
+      getConnection: vi.fn().mockResolvedValue({workspaceId: crypto.randomUUID()}),
+      deleteSecrets,
+      deregisterWebhooks,
+      transaction,
+      deleteConnection,
+    });
+
+    expect(deregisterWebhooks).toHaveBeenCalledOnce();
+    expect(deleteSecrets).toHaveBeenCalledOnce();
+    expect(deleteConnection).toHaveBeenCalledOnce();
+  });
+
+  it('uses a fresh access token and the stored webhook ids for deregistration', async () => {
+    const connectionId = crypto.randomUUID();
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-access-token');
+    const deleteDynamicWebhooks = vi.fn().mockResolvedValue(undefined);
+
+    await deregisterJiraWebhooks({
+      connectionId,
+      tokenStore: {getAccessToken},
+      jira: {deleteDynamicWebhooks},
+      getInstallation: vi.fn().mockResolvedValue({
+        cloudId: 'cloud-1',
+        webhookIds: [123, 456],
+      } as JiraInstallation),
+    });
+
+    expect(getAccessToken).toHaveBeenCalledWith({connectionId, allowInactive: true});
+    expect(deleteDynamicWebhooks).toHaveBeenCalledWith({
+      accessToken: 'fresh-access-token',
+      cloudId: 'cloud-1',
+      webhookIds: [123, 456],
+    });
+  });
+
+  it('uses the database installation lookup by default', async () => {
+    const connectionId = crypto.randomUUID();
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-access-token');
+    const deleteDynamicWebhooks = vi.fn().mockResolvedValue(undefined);
+    getInstallation.mockResolvedValue({
+      cloudId: 'cloud-1',
+      webhookIds: [123],
+    } as JiraInstallation);
+
+    await deregisterJiraWebhooks({
+      connectionId,
+      tokenStore: {getAccessToken},
+      jira: {deleteDynamicWebhooks},
+    });
+
+    expect(getInstallation).toHaveBeenCalledWith(connectionId);
+    expect(deleteDynamicWebhooks).toHaveBeenCalledWith({
+      accessToken: 'fresh-access-token',
+      cloudId: 'cloud-1',
+      webhookIds: [123],
+    });
+  });
+
+  it.each([
+    {name: 'the installation is gone', installation: undefined},
+    {name: 'no webhook ids are stored', installation: {cloudId: 'cloud-1', webhookIds: []}},
+  ])('skips deregistration and token minting when $name', async ({installation}) => {
+    const getAccessToken = vi.fn();
+    const deleteDynamicWebhooks = vi.fn();
+
+    await deregisterJiraWebhooks({
+      connectionId: crypto.randomUUID(),
+      tokenStore: {getAccessToken},
+      jira: {deleteDynamicWebhooks},
+      getInstallation: vi.fn().mockResolvedValue(installation as JiraInstallation | undefined),
+    });
+
+    expect(getAccessToken).not.toHaveBeenCalled();
+    expect(deleteDynamicWebhooks).not.toHaveBeenCalled();
+  });
+
+  it('swallows a rejected Jira deletion so the disconnect can proceed', async () => {
+    const deleteDynamicWebhooks = vi.fn().mockRejectedValue(new Error('Jira unavailable'));
+
+    await expect(
+      deregisterJiraWebhooks({
+        connectionId: crypto.randomUUID(),
+        tokenStore: {getAccessToken: vi.fn().mockResolvedValue('fresh-access-token')},
+        jira: {deleteDynamicWebhooks},
+        getInstallation: vi.fn().mockResolvedValue({
+          cloudId: 'cloud-1',
+          webhookIds: [123],
+        } as JiraInstallation),
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(deleteDynamicWebhooks).toHaveBeenCalledOnce();
+  });
 });

package/src/core/disconnect.ts

@@ -1,10 +1,65 @@
-import {deleteJiraInstallationByConnectionId} from '#db/installations.js';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {JiraApiClient} from '#api/client.js';
+import {
+  deleteJiraInstallationByConnectionId,
+  getJiraInstallationByConnectionId,
+  type JiraInstallation,
+} from '#db/installations.js';
+import type {JiraTokenStore} from './tokens.js';
 import {jiraSecretsNamespace} from './tokens.js';
 
+export interface DeregisterJiraWebhooksParams {
+  connectionId: string;
+  tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+  jira: Pick<JiraApiClient, 'deleteDynamicWebhooks'>;
+  getInstallation?: (connectionId: string) => Promise<JiraInstallation | undefined>;
+}
+
+export async function prepareJiraWebhookDeregistration(
+  params: DeregisterJiraWebhooksParams,
+): Promise<(() => Promise<void>) | undefined> {
+  try {
+    const getInstallation = params.getInstallation ?? getJiraInstallationByConnectionId;
+    const installation = await getInstallation(params.connectionId);
+    if (!installation || installation.webhookIds.length === 0) return undefined;
+
+    const accessToken = await params.tokenStore.getAccessToken({
+      connectionId: params.connectionId,
+      allowInactive: true,
+    });
+    return async () => {
+      try {
+        await params.jira.deleteDynamicWebhooks({
+          accessToken,
+          cloudId: installation.cloudId,
+          webhookIds: installation.webhookIds,
+        });
+      } catch (error) {
+        logger().warn(
+          {err: error, connectionId: params.connectionId},
+          'Jira webhook deregistration failed during disconnect',
+        );
+      }
+    };
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId: params.connectionId},
+      'Jira webhook deregistration preparation failed during disconnect',
+    );
+    return undefined;
+  }
+}
+
+export async function deregisterJiraWebhooks(params: DeregisterJiraWebhooksParams): Promise<void> {
+  const cleanup = await prepareJiraWebhookDeregistration(params);
+  await cleanup?.();
+}
+
 export interface DisconnectJiraInstallationParams<Tx = unknown> {
   connectionId: string;
   getConnection(connectionId: string): Promise<{workspaceId: string} | undefined>;
   deleteSecrets(params: {workspaceId: string; namespace: string}): Promise<number>;
+  deregisterWebhooks?: (() => Promise<void>) | undefined;
   transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
   deleteConnection(params: {connectionId: string}, options: {tx: Tx}): Promise<boolean>;
 }
@@ -13,6 +68,14 @@ export async function disconnectJiraInstallation<Tx = unknown>(
   params: DisconnectJiraInstallationParams<Tx>,
 ): Promise<void> {
   const connection = await params.getConnection(params.connectionId);
+  try {
+    await params.deregisterWebhooks?.();
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId: params.connectionId},
+      'Jira webhook deregistration hook failed during disconnect',
+    );
+  }
   if (connection)
     await params.deleteSecrets({
       workspaceId: connection.workspaceId,

package/src/core/install.test.ts

@@ -21,6 +21,8 @@ function createParams() {
     getMyself: vi.fn().mockResolvedValue({accountId: 'account-1'}),
     refreshAccessToken: vi.fn(),
     registerDynamicWebhook: vi.fn(),
+    refreshDynamicWebhooks: vi.fn(),
+    deleteDynamicWebhooks: vi.fn(),
     deleteDynamicWebhook: vi.fn(),
   };
   const tokenStore = {storeTokens: vi.fn().mockResolvedValue(undefined)};
@@ -190,6 +192,27 @@ describe('Jira OAuth installation', () => {
     expect(params.disconnectJiraInstallation).not.toHaveBeenCalled();
   });
 
+  it('compensates a new connection without reacquiring the installation lock', async () => {
+    const params = createParams();
+    params.jira.getAccessibleResources.mockResolvedValue([
+      {
+        cloudId: 'cloud-1',
+        name: 'Acme',
+        url: 'https://acme.atlassian.net',
+        scopes: ['read:jira-work'],
+      },
+    ]);
+    const storageError = new Error('secret storage unavailable');
+    params.tokenStore.storeTokens.mockRejectedValue(storageError);
+
+    await expect(handleJiraCallback(params)).rejects.toBe(storageError);
+
+    expect(params.disconnectJiraInstallation).toHaveBeenCalledWith({
+      connectionId: 'connection-1',
+      lockAlreadyHeld: true,
+    });
+  });
+
   it('falls back to a second error-state write when the registration callback cannot persist it', async () => {
     const params = createParams();
     params.jira.getAccessibleResources.mockResolvedValue([

package/src/core/install.ts

@@ -58,7 +58,10 @@ export interface HandleJiraCallbackParams {
   withJiraInstallationLock?: JiraInstallationLock;
   markConnectionActive(input: {connectionId: string; tx?: unknown}): Promise<void>;
   markConnectionError(input: {connectionId: string; tx?: unknown}): Promise<void>;
-  disconnectJiraInstallation(input: {connectionId: string}): Promise<void>;
+  disconnectJiraInstallation(input: {
+    connectionId: string;
+    lockAlreadyHeld?: boolean | undefined;
+  }): Promise<void>;
 }
 
 export async function handleJiraCallback(
@@ -226,7 +229,7 @@ async function bestEffortDisconnect(
   connectionId: string,
 ): Promise<void> {
   try {
-    await params.disconnectJiraInstallation({connectionId});
+    await params.disconnectJiraInstallation({connectionId, lockAlreadyHeld: true});
   } catch (error) {
     logger().warn(
       {err: error, connectionId},

package/src/core/tokens-refresh.test.ts

@@ -33,6 +33,8 @@ function createStore() {
     getAccessibleResources: vi.fn(),
     getMyself: vi.fn(),
     registerDynamicWebhook: vi.fn(),
+    refreshDynamicWebhooks: vi.fn(),
+    deleteDynamicWebhooks: vi.fn(),
     deleteDynamicWebhook: vi.fn(),
   };
   const markConnectionError = vi.fn().mockResolvedValue(undefined);
@@ -304,6 +306,43 @@ describe('Jira token refresh', () => {
     );
   });
 
+  it('allows cleanup to use the stored token for an inactive connection', async () => {
+    const {connectionId, resolveConnection, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    resolveConnection.mockResolvedValue({
+      workspaceId: crypto.randomUUID(),
+      lifecycleStatus: 'error',
+    });
+    getInstallation.mockResolvedValue({tokenExpiresAt: null});
+
+    await expect(store.getAccessToken({connectionId})).rejects.toBeInstanceOf(
+      JiraTokenUnrefreshableError,
+    );
+    await expect(store.getAccessToken({connectionId, allowInactive: true})).resolves.toBe(
+      'access-0',
+    );
+  });
+
+  it('refreshes an expired token for inactive cleanup', async () => {
+    const {client, connectionId, resolveConnection, store} = createStore();
+    await store.storeTokens({connectionId, accessToken: 'access-0', refreshToken: 'refresh-0'});
+    resolveConnection.mockResolvedValue({
+      workspaceId: crypto.randomUUID(),
+      lifecycleStatus: 'error',
+    });
+    client.refreshAccessToken.mockResolvedValue({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      expiresAt: new Date('2030-01-01'),
+      scopes: [],
+    });
+
+    await expect(store.getAccessToken({connectionId, allowInactive: true})).resolves.toBe(
+      'access-1',
+    );
+    expect(client.refreshAccessToken).toHaveBeenCalledWith({refreshToken: 'refresh-0'});
+  });
+
   it('requires a refresh token once the access token expires', async () => {
     const {connectionId, store} = createStore();
     await store.storeTokens({connectionId, accessToken: 'access-0'});

package/src/core/tokens.ts

@@ -50,6 +50,8 @@ export interface StoreJiraTokensParams {
 export interface GetJiraAccessTokenParams {
   connectionId: string;
   forceRefresh?: boolean | undefined;
+  /** Allows cleanup to use the stored token after a connection leaves the active state. */
+  allowInactive?: boolean | undefined;
 }
 
 export interface JiraTokenStore {
@@ -139,11 +141,11 @@ export function createJiraTokenStore(params: CreateJiraTokenStoreParams): JiraTo
     async getAccessToken(input) {
       await waitForCredentialWrites(input.connectionId);
       const connection = await resolveConnection(input.connectionId);
-      if (connection.lifecycleStatus !== 'active') {
+      if (!input.allowInactive && connection.lifecycleStatus !== 'active') {
         throw new JiraTokenUnrefreshableError(input.connectionId);
       }
       await waitForCredentialWrites(input.connectionId);
-      if (refreshStateUnknownConnections.has(input.connectionId)) {
+      if (!input.allowInactive && refreshStateUnknownConnections.has(input.connectionId)) {
         throw new JiraTokenUnrefreshableError(input.connectionId);
       }
       const credentialGeneration = currentCredentialGeneration(input.connectionId);

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

@@ -275,6 +275,38 @@ describe('registerJiraWebhook', () => {
     expect(deleteDynamicWebhook).toHaveBeenCalledTimes(2);
   });
 
+  it('retains a failed superseded webhook id when renewal replaces stale metadata', async () => {
+    const updateInstallation = vi
+      .fn()
+      .mockResolvedValueOnce({id: 'installation-1'})
+      .mockResolvedValueOnce({id: 'installation-1'});
+    const deleteDynamicWebhook = vi.fn().mockRejectedValue(new Error('webhook is gone'));
+
+    await registerJiraWebhook({
+      jira: {
+        registerDynamicWebhook: vi.fn().mockResolvedValue({webhookId: 456}),
+        deleteDynamicWebhook,
+      },
+      connectionId: 'connection-1',
+      cloudId: 'cloud-1',
+      accessToken: 'access-token',
+      webhookUrl: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      getInstallation: vi.fn().mockResolvedValue({webhookIds: [123]}),
+      updateInstallation,
+      withRegistrationLock: runInlineRegistrationLock,
+      replaceExistingWebhooks: true,
+    });
+
+    expect(updateInstallation).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({webhookIds: [456]}),
+    );
+    expect(updateInstallation).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({webhookIds: [456, 123]}),
+    );
+  });
+
   it('keeps conservative metadata when failed cleanup cannot be persisted', async () => {
     const updateInstallation = vi
       .fn()

package/src/core/webhook-registration.ts

@@ -19,6 +19,7 @@ export interface RegisterJiraWebhookParams {
   getInstallation?: typeof getJiraInstallationByConnectionId;
   updateInstallation?: typeof updateJiraInstallationWebhook;
   withRegistrationLock?: JiraInstallationLock;
+  replaceExistingWebhooks?: boolean | undefined;
   onRegistrationSuccess?: (input: {tx?: unknown}) => Promise<void>;
   onRegistrationFailure?: (input: {tx?: unknown}) => Promise<void>;
 }
@@ -51,7 +52,9 @@ export async function registerJiraWebhook(
         const updateInstallation = params.updateInstallation ?? updateJiraInstallationWebhook;
         const updateInput = {
           connectionId: params.connectionId,
-          webhookIds: [...new Set([registration.webhookId, ...(previous?.webhookIds ?? [])])],
+          webhookIds: params.replaceExistingWebhooks
+            ? [registration.webhookId]
+            : [...new Set([registration.webhookId, ...(previous?.webhookIds ?? [])])],
           webhookExpiresAt,
         };
         const installation = await updateInstallation(updateInput);

package/src/core/webhook-url.ts

@@ -0,0 +1,9 @@
+import {config} from '#config.js';
+
+export const JIRA_WEBHOOK_ROUTE_PREFIX = '/webhooks/integrations/jira';
+
+const TRAILING_SLASHES_RE = /\/+$/;
+
+export function jiraWebhookUrl(connectionId: string): string {
+  return `${config.JIRA_WEBHOOK_BASE_URL.replace(TRAILING_SLASHES_RE, '')}${JIRA_WEBHOOK_ROUTE_PREFIX}/${connectionId}`;
+}