@shipfox/api-integration-jira 10.2.0 → 12.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-jira",
   "license": "MIT",
-  "version": "10.2.0",
+  "version": "12.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -20,14 +20,16 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "ky": "^2.0.0",
-    "@shipfox/api-auth-context": "10.2.0",
-    "@shipfox/api-integration-spi": "0.2.2",
-    "@shipfox/api-integration-jira-dto": "9.0.2",
+    "zod": "^4.4.3",
+    "@shipfox/api-auth-context": "12.0.0",
+    "@shipfox/api-integration-spi": "1.0.0",
     "@shipfox/config": "1.2.4",
-    "@shipfox/node-drizzle": "0.3.4",
-    "@shipfox/node-fastify": "0.4.0",
+    "@shipfox/node-drizzle": "0.3.5",
+    "@shipfox/api-integration-jira-dto": "12.0.0",
+    "@shipfox/node-fastify": "0.4.1",
     "@shipfox/node-opentelemetry": "0.6.3",
-    "@shipfox/node-postgres": "0.4.4"
+    "@shipfox/node-postgres": "0.5.0",
+    "@shipfox/node-jwt": "0.4.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/api/client.test.ts

@@ -2,6 +2,28 @@ import {HTTPError} from 'ky';
 import type {JiraIntegrationProviderError} from '#core/errors.js';
 import {mapJiraError} from './client.js';
 
+const mocks = vi.hoisted(() => ({delete: vi.fn(), post: vi.fn()}));
+
+vi.mock('ky', () => {
+  class MockHTTPError extends Error {
+    constructor(public response: {status: number; statusText?: string; headers: Headers}) {
+      super('http');
+      this.name = 'HTTPError';
+    }
+  }
+  class MockTimeoutError extends Error {
+    constructor() {
+      super('timeout');
+      this.name = 'TimeoutError';
+    }
+  }
+  return {
+    default: {delete: mocks.delete, post: mocks.post},
+    HTTPError: MockHTTPError,
+    TimeoutError: MockTimeoutError,
+  };
+});
+
 function rejectedRequest(status: number): () => Promise<never> {
   return () =>
     Promise.reject(
@@ -27,3 +49,87 @@ describe('mapJiraError', () => {
     } satisfies Partial<JiraIntegrationProviderError>);
   });
 });
+
+function resolves(data: unknown) {
+  return {json: () => Promise.resolve(data)};
+}
+
+describe('Jira dynamic webhook API', () => {
+  beforeEach(() => {
+    mocks.delete.mockReset();
+    mocks.post.mockReset();
+  });
+
+  it('registers the six curated events with the access token', async () => {
+    mocks.post.mockReturnValue(
+      resolves({webhookRegistrationResult: [{createdWebhookId: 123, errors: []}]}),
+    );
+
+    const {createJiraApiClient} = await import('./client.js');
+    const result = await createJiraApiClient().registerDynamicWebhook({
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+    });
+
+    const [url, options] = mocks.post.mock.calls[0] as [
+      string,
+      {headers: Record<string, string>; json: Record<string, unknown>},
+    ];
+    expect(url).toBe('http://127.0.0.1:0/ex/jira/cloud-1/rest/api/3/webhook');
+    expect(options.headers).toEqual({authorization: 'Bearer access-token'});
+    expect(options.json).toEqual({
+      url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      webhooks: [
+        {
+          events: [
+            'jira:issue_created',
+            'jira:issue_updated',
+            'jira:issue_deleted',
+            'comment_created',
+            'comment_updated',
+            'comment_deleted',
+          ],
+          jqlFilter: '',
+        },
+      ],
+    });
+    expect(result).toEqual({webhookId: 123});
+  });
+
+  it.each([
+    {webhookRegistrationResult: []},
+    {webhookRegistrationResult: [{createdWebhookId: 123, errors: ['rejected']}]},
+    {webhookRegistrationResult: [{errors: []}]},
+  ])('rejects malformed or errored registration responses', async (response) => {
+    mocks.post.mockReturnValue(resolves(response));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+
+  it('deletes a dynamic webhook by id', async () => {
+    mocks.delete.mockResolvedValue(undefined);
+    const {createJiraApiClient} = await import('./client.js');
+
+    await createJiraApiClient().deleteDynamicWebhook({
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      webhookId: 123,
+    });
+
+    expect(mocks.delete).toHaveBeenCalledWith(
+      'http://127.0.0.1:0/ex/jira/cloud-1/rest/api/3/webhook',
+      expect.objectContaining({
+        headers: {authorization: 'Bearer access-token'},
+        json: {webhookIds: [123]},
+      }),
+    );
+  });
+});

package/src/api/client.ts

@@ -1,3 +1,4 @@
+import {jiraWebhookEventNames} from '@shipfox/api-integration-jira-dto';
 import {logger} from '@shipfox/node-opentelemetry';
 import ky, {HTTPError, TimeoutError} from 'ky';
 import {config} from '#config.js';
@@ -5,6 +6,8 @@ import {JiraIntegrationProviderError} from '#core/errors.js';
 
 const JIRA_API_TIMEOUT_MS = 10_000;
 const SCOPE_SEPARATOR_RE = /[,\s]+/;
+export const JIRA_DYNAMIC_WEBHOOK_EVENTS = jiraWebhookEventNames;
+export const JIRA_DYNAMIC_WEBHOOK_JQL = '';
 
 export interface JiraAuthorization {
   accessToken: string;
@@ -24,11 +27,25 @@ export interface JiraIdentity {
   accountId: string;
 }
 
+export interface JiraDynamicWebhookRegistration {
+  webhookId: number;
+}
+
 export interface JiraApiClient {
   exchangeAuthorizationCode(input: {code: string}): Promise<JiraAuthorization>;
   refreshAccessToken(input: {refreshToken: string}): Promise<JiraAuthorization>;
   getAccessibleResources(input: {accessToken: string}): Promise<JiraAccessibleResource[]>;
   getMyself(input: {accessToken: string; cloudId: string}): Promise<JiraIdentity>;
+  registerDynamicWebhook(input: {
+    accessToken: string;
+    cloudId: string;
+    url: string;
+  }): Promise<JiraDynamicWebhookRegistration>;
+  deleteDynamicWebhook(input: {
+    accessToken: string;
+    cloudId: string;
+    webhookId: number;
+  }): Promise<void>;
 }
 
 interface JiraTokenResponse {
@@ -49,6 +66,10 @@ interface JiraMyselfResponse {
   accountId?: unknown;
 }
 
+interface JiraDynamicWebhookRegistrationResponse {
+  webhookRegistrationResult?: unknown;
+}
+
 export function createJiraApiClient(): JiraApiClient {
   return {
     async exchangeAuthorizationCode(input) {
@@ -115,9 +136,73 @@ export function createJiraApiClient(): JiraApiClient {
       }
       return {accountId: body.accountId};
     },
+
+    async registerDynamicWebhook(input) {
+      const body = await mapJiraError('register-dynamic-webhook', () =>
+        ky
+          .post(`${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook`, {
+            headers: {authorization: `Bearer ${input.accessToken}`},
+            json: {
+              url: input.url,
+              webhooks: [
+                {
+                  events: JIRA_DYNAMIC_WEBHOOK_EVENTS,
+                  jqlFilter: JIRA_DYNAMIC_WEBHOOK_JQL,
+                },
+              ],
+            },
+            timeout: JIRA_API_TIMEOUT_MS,
+          })
+          .json<JiraDynamicWebhookRegistrationResponse>(),
+      );
+      return parseDynamicWebhookRegistration(body);
+    },
+
+    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,
+        }),
+      );
+    },
   };
 }
 
+function parseDynamicWebhookRegistration(
+  body: JiraDynamicWebhookRegistrationResponse,
+): JiraDynamicWebhookRegistration {
+  if (
+    !body ||
+    typeof body !== 'object' ||
+    !Array.isArray(body.webhookRegistrationResult) ||
+    body.webhookRegistrationResult.length !== 1
+  ) {
+    throw malformed('Jira webhook registration response did not contain exactly one result');
+  }
+
+  const result = body.webhookRegistrationResult[0];
+  if (!result || typeof result !== 'object') {
+    throw malformed('Jira webhook registration result was malformed');
+  }
+  const {createdWebhookId, errors} = result as {
+    createdWebhookId?: unknown;
+    errors?: unknown;
+  };
+  if (errors !== undefined && (!Array.isArray(errors) || errors.length > 0)) {
+    throw malformed('Jira webhook registration returned errors');
+  }
+  if (
+    typeof createdWebhookId !== 'number' ||
+    !Number.isSafeInteger(createdWebhookId) ||
+    createdWebhookId <= 0
+  ) {
+    throw malformed('Jira webhook registration did not return a created webhook id');
+  }
+  return {webhookId: createdWebhookId};
+}
+
 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/config.test.ts

@@ -2,7 +2,6 @@ const jiraEnvNames = [
   'JIRA_OAUTH_CLIENT_ID',
   'JIRA_OAUTH_CLIENT_SECRET',
   'JIRA_OAUTH_REDIRECT_URL',
-  'JIRA_WEBHOOK_SIGNING_SECRET',
   'JIRA_WEBHOOK_BASE_URL',
 ] as const;
 

package/src/config.ts

@@ -5,14 +5,11 @@ export const config = createConfig({
     desc: 'OAuth client ID of the Jira app, used to start and complete the Jira connect flow. Required.',
   }),
   JIRA_OAUTH_CLIENT_SECRET: str({
-    desc: 'OAuth client secret of the Jira app, used to exchange authorization codes for access and refresh tokens. Required.',
+    desc: 'OAuth client secret of the Jira app, used for authorization-code exchange and inbound webhook JWT verification. Required.',
   }),
   JIRA_OAUTH_REDIRECT_URL: url({
     desc: 'Public client callback URL Jira redirects to after OAuth authorization, such as https://shipfox.example.com/integrations/jira/callback. Required.',
   }),
-  JIRA_WEBHOOK_SIGNING_SECRET: str({
-    desc: 'Secret used to verify incoming Jira webhooks. It must match the webhook signing secret configured for the Jira app. Required.',
-  }),
   JIRA_WEBHOOK_BASE_URL: url({
     desc: 'Public base URL Jira sends webhooks to. Its origin must be added to the Jira app webhook allowlist. Required.',
   }),

package/src/core/install.test.ts

@@ -1,3 +1,4 @@
+import {type JiraInstallationLock, withJiraInstallationLock} from '#db/installations.js';
 import {
   JiraOfflineAccessNotGrantedError,
   JiraPendingSelectionNotFoundError,
@@ -19,6 +20,8 @@ function createParams() {
     getAccessibleResources: vi.fn(),
     getMyself: vi.fn().mockResolvedValue({accountId: 'account-1'}),
     refreshAccessToken: vi.fn(),
+    registerDynamicWebhook: vi.fn(),
+    deleteDynamicWebhook: vi.fn(),
   };
   const tokenStore = {storeTokens: vi.fn().mockResolvedValue(undefined)};
   const pendingStore = {
@@ -29,6 +32,12 @@ function createParams() {
   const connectJiraInstallation = vi
     .fn()
     .mockResolvedValue({id: 'connection-1', workspaceId, provider: 'jira'});
+  const registerJiraWebhook = vi.fn().mockImplementation(async ({onRegistrationSuccess}) => {
+    await onRegistrationSuccess?.({});
+  });
+  const markConnectionActive = vi.fn().mockResolvedValue(undefined);
+  const markConnectionError = vi.fn().mockResolvedValue(undefined);
+  const withJiraInstallationLock: JiraInstallationLock = async (_key, fn) => fn();
   return {
     workspaceId,
     state,
@@ -36,6 +45,10 @@ function createParams() {
     tokenStore,
     pendingStore,
     connectJiraInstallation,
+    registerJiraWebhook,
+    markConnectionActive,
+    markConnectionError,
+    withJiraInstallationLock,
     code: 'code',
     sessionUserId: 'user-1',
     sessionMemberships: [],
@@ -66,6 +79,7 @@ describe('Jira OAuth installation', () => {
     expect(params.tokenStore.storeTokens).toHaveBeenCalledWith(
       expect.objectContaining({connectionId: 'connection-1', refreshToken: 'refresh'}),
     );
+    expect(params.markConnectionActive).toHaveBeenCalledWith({connectionId: 'connection-1'});
   });
 
   it('stores a multi-site grant until the selected site completes', async () => {
@@ -126,4 +140,169 @@ describe('Jira OAuth installation', () => {
       handleJiraSiteSelection({...mismatchedSite, cloudId: 'cloud-1'}),
     ).rejects.toBeInstanceOf(JiraSiteSelectionMismatchError);
   });
+
+  it('marks the connection in error while retaining state when registration fails', async () => {
+    const params = createParams();
+    params.jira.getAccessibleResources.mockResolvedValue([
+      {
+        cloudId: 'cloud-1',
+        name: 'Acme',
+        url: 'https://acme.atlassian.net',
+        scopes: ['read:jira-work'],
+      },
+    ]);
+    const registrationError = new Error('Jira rejected the webhook');
+    params.registerJiraWebhook.mockRejectedValue(registrationError);
+    await expect(handleJiraCallback(params)).rejects.toBe(registrationError);
+    expect(params.tokenStore.storeTokens).toHaveBeenCalled();
+    expect(params.disconnectJiraInstallation).not.toHaveBeenCalled();
+    expect(params.markConnectionError).toHaveBeenCalledWith({connectionId: 'connection-1'});
+  });
+
+  it('does not overwrite an existing installation when token storage fails', async () => {
+    const params = createParams();
+    params.jira.getAccessibleResources.mockResolvedValue([
+      {
+        cloudId: 'cloud-1',
+        name: 'Acme',
+        url: 'https://acme.atlassian.net',
+        scopes: ['read:jira-work'],
+      },
+    ]);
+    const existing = {
+      id: 'connection-1',
+      workspaceId: params.workspaceId,
+      provider: 'jira',
+    } as const;
+    params.getExistingJiraConnection.mockResolvedValue(existing);
+    const storageError = new Error('secret storage unavailable');
+    params.tokenStore.storeTokens.mockRejectedValue(storageError);
+    params.markConnectionError
+      .mockRejectedValueOnce(new Error('database unavailable'))
+      .mockResolvedValueOnce(undefined);
+
+    await expect(handleJiraCallback(params)).rejects.toBe(storageError);
+
+    expect(params.connectJiraInstallation).not.toHaveBeenCalled();
+    expect(params.markConnectionError).toHaveBeenCalledTimes(2);
+    expect(params.markConnectionError).toHaveBeenNthCalledWith(1, {connectionId: existing.id});
+    expect(params.markConnectionError).toHaveBeenNthCalledWith(2, {connectionId: existing.id});
+    expect(params.disconnectJiraInstallation).not.toHaveBeenCalled();
+  });
+
+  it('falls back to a second error-state write when the registration callback cannot persist it', async () => {
+    const params = createParams();
+    params.jira.getAccessibleResources.mockResolvedValue([
+      {
+        cloudId: 'cloud-1',
+        name: 'Acme',
+        url: 'https://acme.atlassian.net',
+        scopes: ['read:jira-work'],
+      },
+    ]);
+    const registrationError = new Error('Jira rejected the webhook');
+    params.registerJiraWebhook.mockImplementation(async ({onRegistrationFailure}) => {
+      await onRegistrationFailure?.({});
+      throw registrationError;
+    });
+    params.markConnectionError
+      .mockRejectedValueOnce(new Error('database unavailable'))
+      .mockResolvedValueOnce(undefined);
+
+    await expect(handleJiraCallback(params)).rejects.toBe(registrationError);
+
+    expect(params.markConnectionError).toHaveBeenCalledTimes(2);
+    expect(params.markConnectionError).toHaveBeenNthCalledWith(1, {connectionId: 'connection-1'});
+    expect(params.markConnectionError).toHaveBeenNthCalledWith(2, {connectionId: 'connection-1'});
+  });
+
+  it('serializes the complete same-site replacement before allowing another callback to proceed', async () => {
+    const first = createParams();
+    const second = createParams();
+    second.workspaceId = first.workspaceId;
+    second.state = signJiraInstallState({workspaceId: first.workspaceId, userId: 'user-1'});
+    const sites = [
+      {
+        cloudId: 'cloud-1',
+        name: 'Acme',
+        url: 'https://acme.atlassian.net',
+        scopes: ['read:jira-work'],
+      },
+    ];
+    const connection = {id: 'connection-1', workspaceId: first.workspaceId, provider: 'jira'};
+    const getExisting = vi.fn().mockResolvedValue(undefined);
+    const connect = vi.fn().mockResolvedValue(connection);
+    const storeTokens = vi.fn().mockResolvedValue(undefined);
+    const register = vi.fn();
+    const events: string[] = [];
+    let releaseFirstRegistration!: () => void;
+    const firstRegistrationReady = new Promise<void>((resolve) => {
+      releaseFirstRegistration = resolve;
+    });
+
+    first.jira.getAccessibleResources.mockResolvedValue(sites);
+    second.jira.getAccessibleResources.mockResolvedValue(sites);
+    first.jira.getMyself.mockResolvedValue({accountId: 'account-1'});
+    second.jira.getMyself.mockResolvedValue({accountId: 'account-2'});
+    first.jira.exchangeAuthorizationCode.mockResolvedValue({
+      accessToken: 'access-1',
+      refreshToken: 'refresh-1',
+      scopes: [],
+    });
+    second.jira.exchangeAuthorizationCode.mockResolvedValue({
+      accessToken: 'access-2',
+      refreshToken: 'refresh-2',
+      scopes: [],
+    });
+    getExisting.mockImplementation(() => {
+      events.push('get-existing');
+      return Promise.resolve(connect.mock.calls.length > 0 ? connection : undefined);
+    });
+    connect.mockImplementation((input) => {
+      events.push(`connect:${input.authorizingAccountId}`);
+      return Promise.resolve(connection);
+    });
+    storeTokens.mockImplementation(({accessToken}) => {
+      events.push(`store:${accessToken}`);
+      return Promise.resolve();
+    });
+    register.mockImplementation(async ({accessToken, onRegistrationSuccess}) => {
+      events.push(`register:${accessToken}`);
+      if (accessToken === 'access-1') await firstRegistrationReady;
+      await onRegistrationSuccess?.({});
+    });
+
+    for (const params of [first, second]) {
+      params.getExistingJiraConnection = getExisting;
+      params.connectJiraInstallation = connect;
+      params.tokenStore.storeTokens = storeTokens;
+      params.registerJiraWebhook = register;
+    }
+
+    first.withJiraInstallationLock = withJiraInstallationLock;
+    second.withJiraInstallationLock = withJiraInstallationLock;
+
+    const firstCallback = handleJiraCallback(first);
+    await vi.waitFor(() =>
+      expect(register).toHaveBeenCalledWith(expect.objectContaining({accessToken: 'access-1'})),
+    );
+    const secondCallback = handleJiraCallback(second);
+    await Promise.resolve();
+    expect(getExisting).toHaveBeenCalledTimes(1);
+
+    releaseFirstRegistration();
+    await expect(firstCallback).resolves.toMatchObject({id: 'connection-1'});
+    await expect(secondCallback).resolves.toMatchObject({id: 'connection-1'});
+
+    expect(events).toEqual([
+      'get-existing',
+      'connect:account-1',
+      'store:access-1',
+      'register:access-1',
+      'get-existing',
+      'store:access-2',
+      'connect:account-2',
+      'register:access-2',
+    ]);
+  });
 });

package/src/core/install.ts

@@ -4,6 +4,7 @@ import {logger} from '@shipfox/node-opentelemetry';
 import type {JiraAccessibleResource, JiraApiClient, JiraAuthorization} from '#api/client.js';
 import type {JiraPendingSelectionStore} from '#core/pending.js';
 import type {JiraTokenStore} from '#core/tokens.js';
+import {type JiraInstallationLock, withJiraInstallationLock} from '#db/installations.js';
 import {
   JiraInstallationAlreadyLinkedError,
   JiraInstallStateActorMismatchError,
@@ -46,6 +47,17 @@ export interface HandleJiraCallbackParams {
   connectJiraInstallation(
     input: ConnectJiraInstallationInput,
   ): Promise<IntegrationConnection<'jira'>>;
+  registerJiraWebhook(input: {
+    connectionId: string;
+    cloudId: string;
+    accessToken: string;
+    withRegistrationLock?: JiraInstallationLock;
+    onRegistrationSuccess: (input: {tx?: unknown}) => Promise<void>;
+    onRegistrationFailure: (input: {tx?: unknown}) => Promise<void>;
+  }): Promise<void>;
+  withJiraInstallationLock?: JiraInstallationLock;
+  markConnectionActive(input: {connectionId: string; tx?: unknown}): Promise<void>;
+  markConnectionError(input: {connectionId: string; tx?: unknown}): Promise<void>;
   disconnectJiraInstallation(input: {connectionId: string}): Promise<void>;
 }
 
@@ -136,23 +148,23 @@ async function verifyClaims(
   return claims;
 }
 
-async function resolveJiraSite(
+function resolveJiraSite(
   params: Omit<HandleJiraCallbackParams, 'code'> & {
     authorization: JiraAuthorization;
     site: JiraAccessibleResource;
     claims: {workspaceId: string; userId: string};
   },
 ): Promise<IntegrationConnection<'jira'>> {
-  const existing = await params.getExistingJiraConnection({cloudId: params.site.cloudId});
-  if (existing && existing.workspaceId !== params.claims.workspaceId)
-    throw new JiraInstallationAlreadyLinkedError(params.site.cloudId);
-  let connectionId: string | undefined;
-  try {
+  const withInstallationLock = params.withJiraInstallationLock ?? withJiraInstallationLock;
+  return withInstallationLock(params.site.cloudId, async () => {
+    const existing = await params.getExistingJiraConnection({cloudId: params.site.cloudId});
+    if (existing && existing.workspaceId !== params.claims.workspaceId)
+      throw new JiraInstallationAlreadyLinkedError(params.site.cloudId);
     const identity = await params.jira.getMyself({
       accessToken: params.authorization.accessToken,
       cloudId: params.site.cloudId,
     });
-    const connection = await params.connectJiraInstallation({
+    const installationInput = {
       workspaceId: params.claims.workspaceId,
       cloudId: params.site.cloudId,
       siteUrl: params.site.url,
@@ -161,19 +173,52 @@ async function resolveJiraSite(
       scopes: params.site.scopes,
       tokenExpiresAt: params.authorization.expiresAt ?? null,
       displayName: `Jira ${params.site.name}`,
-    });
-    connectionId = connection.id;
-    await params.tokenStore.storeTokens({
-      connectionId: connection.id,
-      accessToken: params.authorization.accessToken,
-      refreshToken: params.authorization.refreshToken,
-      editedBy: params.claims.userId,
-    });
+    };
+    let connection = existing;
+    try {
+      if (!connection) connection = await params.connectJiraInstallation(installationInput);
+      await params.tokenStore.storeTokens({
+        connectionId: connection.id,
+        accessToken: params.authorization.accessToken,
+        refreshToken: params.authorization.refreshToken,
+        editedBy: params.claims.userId,
+      });
+      if (existing) connection = await params.connectJiraInstallation(installationInput);
+    } catch (error) {
+      if (existing) {
+        const markedError = await bestEffortMarkConnectionError(params, existing.id);
+        if (!markedError) await bestEffortMarkConnectionError(params, existing.id);
+      } else if (connection) {
+        await bestEffortDisconnect(params, connection.id);
+      }
+      throw error;
+    }
+
+    let registrationFailureHandled = false;
+    try {
+      await params.registerJiraWebhook({
+        connectionId: connection.id,
+        cloudId: params.site.cloudId,
+        accessToken: params.authorization.accessToken,
+        withRegistrationLock: async (_lockKey, fn) => fn(),
+        onRegistrationSuccess: async ({tx}) => {
+          await params.markConnectionActive(connectionLifecycleInput(connection.id, tx));
+        },
+        onRegistrationFailure: async ({tx}) => {
+          registrationFailureHandled = await bestEffortMarkConnectionError(
+            params,
+            connection.id,
+            tx,
+          );
+        },
+      });
+    } catch (error) {
+      if (!registrationFailureHandled) await bestEffortMarkConnectionError(params, connection.id);
+      throw error;
+    }
+
     return connection;
-  } catch (error) {
-    if (connectionId && !existing) await bestEffortDisconnect(params, connectionId);
-    throw error;
-  }
+  });
 }
 
 async function bestEffortDisconnect(
@@ -189,3 +234,24 @@ async function bestEffortDisconnect(
     );
   }
 }
+
+async function bestEffortMarkConnectionError(
+  params: Pick<HandleJiraCallbackParams, 'markConnectionError'>,
+  connectionId: string,
+  tx?: unknown,
+): Promise<boolean> {
+  try {
+    await params.markConnectionError(connectionLifecycleInput(connectionId, tx));
+    return true;
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId},
+      'Jira connection error-state update failed after webhook registration rejection',
+    );
+    return false;
+  }
+}
+
+function connectionLifecycleInput(connectionId: string, tx?: unknown) {
+  return tx === undefined ? {connectionId} : {connectionId, tx};
+}

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

@@ -30,6 +30,8 @@ function createStore() {
     refreshAccessToken: vi.fn(),
     getAccessibleResources: vi.fn(),
     getMyself: vi.fn(),
+    registerDynamicWebhook: vi.fn(),
+    deleteDynamicWebhook: vi.fn(),
   };
   const markConnectionError = vi.fn().mockResolvedValue(undefined);
   const connectionId = crypto.randomUUID();