feat(backend): Add `external_id` to `user.deleted`; Add `user` to `SessionWebhookEventJSON` #7209

kduprey · 2025-11-12T22:14:59Z

Description

Adds external_id field to user.deleted webhook events by creating a new UserDeletedJSON interface that extends DeletedObjectJSON to include an optional external_id string.
Creates a new SessionWebhookEventJSON interface that extends SessionJSON to include a nullable user field as the UserJSON interface, and updates the webhook event types to use this new interface for session.created, session.ended, session.removed, and session.revoked events.

USER-3955

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

New Features
- User deletion webhook payloads now include an optional external identifier.
- Session event webhooks (created, ended, removed, revoked) now include associated user information when available.
Version Updates
- Backend package minor version bumped.

…ts; Add `user` field to `SessionWebhookEventJSON` - Adds `external_id` field to `user.deleted` webhook events by creating a new `UserDeletedJSON` interface that extends `DeletedObjectJSON` to include an optional `external_id` string. - Creates a new `SessionWebhookEventJSON` interface that extends `SessionJSON` to include a nullable `user` field as the `UserJSON` interface, and updates the webhook event types to use this new interface for `session.created`, `session.ended`, `session.removed`, and `session.revoked` events. Signed-off-by: Kenton Duprey <[email protected]>

changeset-bot · 2025-11-12T22:15:03Z

🦋 Changeset detected

Latest commit: 825cce2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

vercel · 2025-11-12T22:15:04Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Nov 12, 2025 10:32pm

coderabbitai · 2025-11-12T22:15:11Z

Walkthrough

Adds two new webhook payload interfaces: UserDeletedJSON includes optional external_id, and SessionWebhookEventJSON includes a nullable user field. Webhook type definitions and imports are updated to use these interfaces; package changeset bumps @clerk/backend minor version.

Changes

Cohort / File(s)	Change Summary
Changeset `.changeset/lovely-tools-sleep.md`	Declares minor version bump for `@clerk/backend`.
Webhook Payload Types `packages/backend/src/api/resources/JSON.ts`	Adds exported interfaces: `SessionWebhookEventJSON` (extends `SessionJSON` with `user: UserJSON
Webhook Event Types `packages/backend/src/api/resources/Webhooks.ts`	Updates imports and webhook event type signatures: session events (`session.created`, `session.ended`, `session.removed`, `session.revoked`) now use `SessionWebhookEventJSON`; `user.deleted` now uses `UserDeletedJSON`.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Focus review on type compatibility and import updates in:
- packages/backend/src/api/resources/JSON.ts
- packages/backend/src/api/resources/Webhooks.ts

Poem

🐰 I hopped in code, a tiny cheer,
New fields for webs and users near,
External IDs and users snug,
Types aligned with gentle hug,
A quiet update — carrot cake for bugs. 🥕

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main changes: adding external_id to user.deleted and user field to SessionWebhookEventJSON, matching the changeset.
Linked Issues check	✅ Passed	All code changes align with USER-3955 objectives: UserDeletedJSON adds optional external_id to user.deleted events, and SessionWebhookEventJSON adds nullable user field to session events [USER-3955].
Out of Scope Changes check	✅ Passed	All changes are in scope: new interfaces for webhook payloads and updated type references are directly related to the objectives in USER-3955.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch kenton/user-3955-update-clerk-js-webhook-event-types-with-updated

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 6f6a986 and 825cce2.

📒 Files selected for processing (1)

packages/backend/src/api/resources/JSON.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels

Files:

packages/backend/src/api/resources/JSON.ts

**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use Prettier for consistent code formatting

Files:

packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

TypeScript is required for all packages

Files:

packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx,d.ts}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Packages should export TypeScript types alongside runtime code

Files:

packages/backend/src/api/resources/JSON.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use proper TypeScript error types

**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoid any type - prefer unknown when type is uncertain, then narrow with type guards
Use interface for object shapes that might be extended
Use type for unions, primitives, and computed types
Prefer readonly properties for immutable data structures
Use private for internal implementation details
Use protected for inheritance hierarchies
Use public explicitly for clarity in public APIs
Prefer readonly for properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Use const assertions for literal types: as const
Use satisfies operator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports: import type { ... } from ...
No any types without justification
Proper error handling with typed errors
Consistent use of readonly for immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)

Files:

packages/backend/src/api/resources/JSON.ts

🧬 Code graph analysis (1)

packages/backend/src/api/resources/JSON.ts (1)

packages/shared/src/types/json.ts (3)

SessionJSON (154-175)

UserJSON (292-330)

DeletedObjectJSON (545-550)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

GitHub Check: Build Packages
GitHub Check: Formatting | Dedupe | Changeset
GitHub Check: semgrep-cloud-platform/scan
GitHub Check: semgrep-cloud-platform/scan
GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (2)

packages/backend/src/api/resources/JSON.ts (2)

501-510: JSDoc documentation successfully added.

The interface now includes comprehensive JSDoc documentation that addresses the previous review feedback. The interface correctly extends SessionJSON and adds a nullable user field for webhook events where the user may not be available (e.g., after account deletion or in privacy-restricted scenarios).

663-673: JSDoc documentation successfully added.

The interface now includes proper JSDoc documentation that addresses the previous review feedback. The optional external_id field is appropriately typed and documented, allowing webhook consumers to track deleted users in external systems when an external identifier was previously set.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2025-11-12T22:18:48Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7209

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7209

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7209

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7209

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7209

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7209

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7209

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@7209

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7209

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7209

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7209

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7209

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7209

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7209

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@7209

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7209

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7209

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7209

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7209

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7209

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7209

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7209

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7209

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7209

commit: 825cce2

coderabbitai

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between b5a7e2f and 6f6a986.

📒 Files selected for processing (3)

.changeset/lovely-tools-sleep.md (1 hunks)
packages/backend/src/api/resources/JSON.ts (2 hunks)
packages/backend/src/api/resources/Webhooks.ts (2 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels

Files:

packages/backend/src/api/resources/Webhooks.ts
packages/backend/src/api/resources/JSON.ts

**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use Prettier for consistent code formatting

Files:

packages/backend/src/api/resources/Webhooks.ts
packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

TypeScript is required for all packages

Files:

packages/backend/src/api/resources/Webhooks.ts
packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx,d.ts}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Packages should export TypeScript types alongside runtime code

Files:

packages/backend/src/api/resources/Webhooks.ts
packages/backend/src/api/resources/JSON.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use proper TypeScript error types

**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoid any type - prefer unknown when type is uncertain, then narrow with type guards
Use interface for object shapes that might be extended
Use type for unions, primitives, and computed types
Prefer readonly properties for immutable data structures
Use private for internal implementation details
Use protected for inheritance hierarchies
Use public explicitly for clarity in public APIs
Prefer readonly for properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Use const assertions for literal types: as const
Use satisfies operator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports: import type { ... } from ...
No any types without justification
Proper error handling with typed errors
Consistent use of readonly for immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)

Files:

packages/backend/src/api/resources/Webhooks.ts
packages/backend/src/api/resources/JSON.ts

🧬 Code graph analysis (2)

packages/backend/src/api/resources/Webhooks.ts (1)

packages/backend/src/api/resources/JSON.ts (2)

UserDeletedJSON (656-658)

SessionWebhookEventJSON (501-503)

packages/backend/src/api/resources/JSON.ts (1)

packages/shared/src/types/json.ts (3)

SessionJSON (154-175)

UserJSON (292-330)

DeletedObjectJSON (545-550)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

GitHub Check: Build Packages
GitHub Check: Formatting | Dedupe | Changeset
GitHub Check: semgrep-cloud-platform/scan
GitHub Check: semgrep-cloud-platform/scan
GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (2)

.changeset/lovely-tools-sleep.md (1)

1-8: LGTM! Changeset is well-documented.

The changeset correctly documents the minor version bump and provides clear descriptions of the new UserDeletedJSON and SessionWebhookEventJSON interfaces.

packages/backend/src/api/resources/Webhooks.ts (1)

14-16: LGTM! Webhook types correctly updated.

The imports and webhook event type definitions are properly updated to use the new SessionWebhookEventJSON and UserDeletedJSON interfaces. The changes correctly:

Add SessionWebhookEventJSON for session webhook events (session.created, session.ended, session.removed, session.revoked)

Add UserDeletedJSON for user.deleted events to include the external_id field

Also applies to: 32-32, 38-41

packages/backend/src/api/resources/JSON.ts

Signed-off-by: Kenton Duprey <[email protected]>

kduprey requested a review from tmilewski November 12, 2025 22:14

kduprey self-assigned this Nov 12, 2025

clerk-cookie added the backend label Nov 12, 2025

tmilewski approved these changes Nov 12, 2025

View reviewed changes

coderabbitai bot reviewed Nov 12, 2025

View reviewed changes

packages/backend/src/api/resources/JSON.ts Show resolved Hide resolved

packages/backend/src/api/resources/JSON.ts Show resolved Hide resolved

kduprey changed the title ~~feat(backend): Add external_id field to user.deleted webhook events; Add user field to SessionWebhookEventJSON~~ feat(backend): Add external_id to user.deleted; Add user to SessionWebhookEventJSON Nov 12, 2025

docs(backend): Add JSDocs for updated interfaces for consumers

825cce2

Signed-off-by: Kenton Duprey <[email protected]>

vercel bot deployed to Preview November 12, 2025 22:32 View deployment

kduprey merged commit 50e630a into main Nov 12, 2025
45 checks passed

kduprey deleted the kenton/user-3955-update-clerk-js-webhook-event-types-with-updated branch November 12, 2025 22:53

clerk-cookie mentioned this pull request Nov 12, 2025

ci(repo): Version packages #7210

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(backend): Add `external_id` to `user.deleted`; Add `user` to `SessionWebhookEventJSON` #7209

feat(backend): Add `external_id` to `user.deleted`; Add `user` to `SessionWebhookEventJSON` #7209

Uh oh!

kduprey commented Nov 12, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Nov 12, 2025 •

edited

Loading

Uh oh!

vercel bot commented Nov 12, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Nov 12, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Nov 12, 2025 •

edited

Loading

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(backend): Add external_id to user.deleted; Add user to SessionWebhookEventJSON #7209

feat(backend): Add external_id to user.deleted; Add user to SessionWebhookEventJSON #7209

Uh oh!

Conversation

kduprey commented Nov 12, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Pre-merge checks and finishing touches

Uh oh!

pkg-pr-new bot commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(backend): Add `external_id` to `user.deleted`; Add `user` to `SessionWebhookEventJSON` #7209

feat(backend): Add `external_id` to `user.deleted`; Add `user` to `SessionWebhookEventJSON` #7209

kduprey commented Nov 12, 2025 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Nov 12, 2025 •

edited

Loading

vercel bot commented Nov 12, 2025 •

edited

Loading

coderabbitai bot commented Nov 12, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 12, 2025 •

edited

Loading