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

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

Author: kduprey

.changeset/lovely-tools-sleep.md

@@ -0,0 +1,8 @@
+---
+'@clerk/backend': minor
+---
+
+Add `external_id` field to `user.deleted` webhook events; 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.

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

@@ -498,6 +498,17 @@ export interface SessionJSON extends ClerkResourceJSON {
   updated_at: number;
 }
 
+/**
+ * Session webhook event payload extending `SessionJSON` interface with associated `User` information.
+ * Used for `session.created`, `session.ended`, `session.removed`, and `session.revoked` webhook events.
+ */
+export interface SessionWebhookEventJSON extends SessionJSON {
+  /**
+   * The user associated with the session, or null if not available.
+   */
+  user: UserJSON | null;
+}
+
 export interface SignInJSON extends ClerkResourceJSON {
   object: typeof ObjectType.SignInToken;
   status: SignInStatus;
@@ -649,6 +660,18 @@ export interface DeletedObjectJSON {
   deleted: boolean;
 }
 
+/**
+ * User deletion webhook event payload that extends `DeletedObjectJSON`.
+ * Includes the `external_id` field to identify the deleted user in external systems.
+ * Used for `user.deleted` webhook events.
+ */
+export interface UserDeletedJSON extends DeletedObjectJSON {
+  /**
+   * The external identifier associated with the deleted user, if one was set.
+   */
+  external_id?: string;
+}
+
 export interface PaginatedResponseJSON {
   data: object[];
   total_count?: number;

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

@@ -11,8 +11,9 @@ import type {
   OrganizationMembershipJSON,
   PermissionJSON,
   RoleJSON,
-  SessionJSON,
+  SessionWebhookEventJSON,
   SMSMessageJSON,
+  UserDeletedJSON,
   UserJSON,
   WaitlistEntryJSON,
 } from './JSON';
@@ -28,15 +29,15 @@ type Webhook<EvtType, Data> = { type: EvtType; object: 'event'; data: Data; even
 
 export type UserWebhookEvent =
   | Webhook<'user.created' | 'user.updated', UserJSON>
-  | Webhook<'user.deleted', DeletedObjectJSON>;
+  | Webhook<'user.deleted', UserDeletedJSON>;
 
 export type EmailWebhookEvent = Webhook<'email.created', EmailJSON>;
 
 export type SMSWebhookEvent = Webhook<'sms.created', SMSMessageJSON>;
 
 export type SessionWebhookEvent = Webhook<
   'session.created' | 'session.ended' | 'session.removed' | 'session.revoked',
-  SessionJSON
+  SessionWebhookEventJSON
 >;
 
 export type OrganizationWebhookEvent =