diff --git a/.changeset/lovely-tools-sleep.md b/.changeset/lovely-tools-sleep.md new file mode 100644 index 00000000000..6371c783115 --- /dev/null +++ b/.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. diff --git a/packages/backend/src/api/resources/JSON.ts b/packages/backend/src/api/resources/JSON.ts index e0eab086a12..2c9ce9d30bb 100644 --- a/packages/backend/src/api/resources/JSON.ts +++ b/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; diff --git a/packages/backend/src/api/resources/Webhooks.ts b/packages/backend/src/api/resources/Webhooks.ts index 16b4d0e1e9c..5d0bcf927a9 100644 --- a/packages/backend/src/api/resources/Webhooks.ts +++ b/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,7 +29,7 @@ type Webhook = { 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>; @@ -36,7 +37,7 @@ export type SMSWebhookEvent = Webhook<'sms.created', SMSMessageJSON>; export type SessionWebhookEvent = Webhook< 'session.created' | 'session.ended' | 'session.removed' | 'session.revoked', - SessionJSON + SessionWebhookEventJSON >; export type OrganizationWebhookEvent =