src: add and delete file webhooks when designs are attached or removed

[Isaiah-Turner]

This PR adds logic to manage creating and deleting webhooks for a file when it is associated or disassociated with a design. It also adds a FigmaFileRepository to make use of the new table from #259.

On association, we now call maybeCreateFigmaFileWebhooks. This function checks to see if the file already has file webhooks with the same file key. If not, we create a FILE_UPDATE and DEV_MODE_STATUS_UPDATE webhook for that file.

On disassociate, we call maybeTryDeleteFigmaFileWebhooks. If there are no longer any linked designs that rely on the webhook, we'll delete them.

Testing

• This PR adds test
• Manually test by linking and unlinking a design. Make sure webhooks show up in DB when design is linked, and get deleted when design is unlinked

Screen.Recording.2025-08-01.at.4.10.13.PM.mov

• Attach same file to multiple issues. Make sure only one set of webhooks show up in DB, and still remain after one design is unlinked. After both are unlinked, they should be deleted

attaching-multiple-design.mov

[Isaiah-Turner]

I replaced some of our custom types with types from our official rest api spec where possible

[akostevich-atlassian]

praise: Amazing! Thank you for doing this, @Isaiah-Turner !

[akostevich-atlassian]

suggestion (npn-blocking): It seems we over-engineered a bit FigmaFileWebhook. This class is just holds data and does not have any business logic associated with it.

We could define FigmaFileWebhook as a read-only type without using classes.

export enum FigmaFileWebhookEventType {
	FILE_UPDATE = 'FILE_UPDATE',
	DEV_MODE_STATUS_UPDATE = 'DEV_MODE_STATUS_UPDATE',
}

export type FigmaFileWebhook = {
	readonly id: string;
	readonly webhookId: string;
	readonly webhookPasscode: string;
	readonly fileKey: string;
	readonly eventType: FigmaFileWebhookEventType;
	readonly createdBy: {
		readonly atlassianUserId: string;
		readonly connectInstallationId: string;
	};
};

export type FigmaFileWebhookCreateParams = {
	readonly webhookId: string;
	readonly webhookPasscode: string;
	readonly fileKey: string;
	readonly eventType: FigmaFileWebhookEventType;
	readonly createdBy: {
		readonly atlassianUserId: string;
		readonly connectInstallationId: string;
	};
};

[Isaiah-Turner]

This is a great point! I fixed this in 6175d34

[akostevich-atlassian]

nitpick Please, could you rename the schema to match the type name (CREATE_WEBHOOK_RESPONSE -> POST_WEBHOOK_RESPONSE) for consistency?

[Isaiah-Turner]

Fixed in 6175d34!

[akostevich-atlassian]

praise: This is so good!

[akostevich-atlassian]

issue: The current behaviour can cause creating "dangling" webhooks in an edge case when the first webhook is successfully created but the creation of the second one fails. This being the case, no webhook will be recorded in our database. As a result, when the operation is retried by Atlassian's platform, the implementation will try to create a new set of webhooks.

In order to minimise the risk of this (it can still happens anyway if the database transaction fails), please, consider the following:

1. Split FigmaService.createFileContextWebhooks into the methods: FigmaService.createFileUpdateWebHook and FigmaService.createDevModeStatusUpdateWebHook.
2. Update maybeCreateFigmaFileWebhooks to accept an additional parameter of type FigmaFileWebhookEventType and take responsibility of the a creation of a single webhook. It could do the following:
   1. Check whether the webhook of the given type exists. If not -- return.
   2. Call FigmaService.createFileContextWebhooks.
   3. Call FigmaFileWebhookRepository.upsert for the created webhook.
3. Call maybeCreateFigmaFileWebhooks for each supported webhook type (once for FILE_UPDATE andonce for DEV_MODE_STATUS_UPDATE).

What do you think, @Isaiah-Turner ?

[Isaiah-Turner]

Yeah, this is a great call. I refactored this how you described in bf0acd7, and added a new test in src/web/routes/entities-v2/integration.test.ts

[akostevich-atlassian]

suggestion (non-blocking): This use case is called on a PUT /entities/onEntityAssociated endpoint request. There are integration tests for this endpoint in src/web/routes/entities-v2/integration.test.ts, which are, likely, passing because the Launch Darkly client falls back to false for the feature gate.

I would highly recommend updating these tests in accordance with the new behaviour within this PR for extra safety.

Beware, that if we delay this work, we will not be able to clean up the feature gate without updating the affected tests.

This is totally fine to do this within a separate PR :)

[akostevich-atlassian]

praise: Great work, @Isaiah-Turner on the feature! And thank you so much for the detailed PR description and demos!

[akostevich-atlassian]

Please, see other comments for more details.

[akostevich-atlassian]

praise: This was a quite large and challenging work, @Isaiah-Turner ! Really love the changes and what they bring to the product. Great job!