feat(backend): Add directory group webhook event types

.changeset/directory-group-webhook-events.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add `DirectoryGroupWebhookEvent` and `DirectoryGroupMembershipWebhookEvent` to `WebhookEvent`, so `verifyWebhook()` narrows the `directoryGroup.created`, `directoryGroup.updated`, `directoryGroup.deleted`, `directoryGroupMembership.created` and `directoryGroupMembership.deleted` events that Directory Sync sends. Their payload types are exported as `DirectoryGroupWebhookEventJSON`, `DirectoryGroupMembershipWebhookEventJSON` and `DeletedDirectoryGroupMembershipWebhookEventJSON`.

packages/backend/src/__tests__/directory-group-webhooks.test.ts

@@ -0,0 +1,28 @@
+import { describe, expectTypeOf, test } from 'vitest';
+
+import type { DirectoryGroupMembershipWebhookEvent, DirectoryGroupWebhookEvent, WebhookEventType } from '../index';
+import type { verifyWebhook } from '../webhooks';
+
+type VerifiedEvent = Awaited<ReturnType<typeof verifyWebhook>>;
+
+describe('directory group webhooks', () => {
+  test('are part of the verified event union', () => {
+    expectTypeOf<DirectoryGroupWebhookEvent>().toMatchTypeOf<VerifiedEvent>();
+    expectTypeOf<DirectoryGroupMembershipWebhookEvent>().toMatchTypeOf<VerifiedEvent>();
+    expectTypeOf<'directoryGroup.deleted'>().toMatchTypeOf<WebhookEventType>();
+    expectTypeOf<'directoryGroupMembership.deleted'>().toMatchTypeOf<WebhookEventType>();
+  });
+
+  test('only the membership deletion carries a cause', () => {
+    type Deleted = Extract<VerifiedEvent, { type: 'directoryGroupMembership.deleted' }>;
+    type Created = Extract<VerifiedEvent, { type: 'directoryGroupMembership.created' }>;
+    expectTypeOf<Deleted['data']['cause']>().toEqualTypeOf<'group_deleted' | 'member_removed'>();
+    expectTypeOf<Created['data']>().not.toHaveProperty('cause');
+    expectTypeOf<Deleted['data']['user_id']>().toEqualTypeOf<string | null>();
+  });
+
+  test('preserve the common resource ID used by existing webhook handlers', () => {
+    expectTypeOf<VerifiedEvent['data']['id']>().toEqualTypeOf<string | undefined>();
+    expectTypeOf<DirectoryGroupWebhookEvent['data']['id']>().toEqualTypeOf<string>();
+  });
+});

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

@@ -33,6 +33,8 @@ export const ObjectType = {
   BlocklistIdentifier: 'blocklist_identifier',
   Client: 'client',
   Cookies: 'cookies',
+  DirectoryGroup: 'directory_group',
+  DirectoryGroupMembership: 'directory_group_membership',
   Domain: 'domain',
   Email: 'email',
   EnterpriseAccount: 'enterprise_account',
@@ -761,6 +763,52 @@ export interface UserDeletedJSON extends DeletedObjectJSON {
   external_id?: string;
 }
 
+/**
+ * Directory group webhook event payload: a group as the identity provider reported it to a directory.
+ * Used for `directoryGroup.created`, `directoryGroup.updated` and `directoryGroup.deleted` webhook events.
+ */
+export interface DirectoryGroupWebhookEventJSON {
+  object: typeof ObjectType.DirectoryGroup;
+  /**
+   * The group ID, as assigned by the directory.
+   */
+  id: string;
+  directory_id: string;
+  display_name: string;
+  updated_at: number;
+}
+
+/**
+ * Directory group membership webhook event payload: one user's membership in a directory group.
+ * `user_id` is null until the member has been provisioned into Clerk.
+ * Used for `directoryGroupMembership.created` webhook events.
+ */
+export interface DirectoryGroupMembershipWebhookEventJSON {
+  object: typeof ObjectType.DirectoryGroupMembership;
+  /**
+   * Never set: the payload has no ID. Declared so `event.data.id` keeps the same type across every `WebhookEvent`.
+   */
+  id?: never;
+  directory_id: string;
+  group: {
+    object: typeof ObjectType.DirectoryGroup;
+    id: string;
+    display_name: string;
+  };
+  directory_user_id: string;
+  user_id: string | null;
+  updated_at: number;
+}
+
+/**
+ * Directory group membership deletion webhook event payload that extends `DirectoryGroupMembershipWebhookEventJSON`
+ * with `cause`: `group_deleted` when the whole group is gone, `member_removed` when the identity provider took this
+ * user out of it. Used for `directoryGroupMembership.deleted` webhook events.
+ */
+export interface DeletedDirectoryGroupMembershipWebhookEventJSON extends DirectoryGroupMembershipWebhookEventJSON {
+  cause: 'group_deleted' | 'member_removed';
+}
+
 export interface PaginatedResponseJSON {
   data: object[];
   total_count?: number;

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

@@ -2,7 +2,10 @@ import type {
   BillingPaymentAttemptWebhookEventJSON,
   BillingSubscriptionItemWebhookEventJSON,
   BillingSubscriptionWebhookEventJSON,
+  DeletedDirectoryGroupMembershipWebhookEventJSON,
   DeletedObjectJSON,
+  DirectoryGroupMembershipWebhookEventJSON,
+  DirectoryGroupWebhookEventJSON,
   EmailJSON,
   OrganizationDomainJSON,
   OrganizationInvitationAcceptedJSON,
@@ -73,6 +76,15 @@ export type EmailDeliveryWebhookEvent =
 
 export type SMSWebhookEvent = Webhook<'sms.created', SMSMessageJSON>;
 
+export type DirectoryGroupWebhookEvent = Webhook<
+  'directoryGroup.created' | 'directoryGroup.updated' | 'directoryGroup.deleted',
+  DirectoryGroupWebhookEventJSON
+>;
+
+export type DirectoryGroupMembershipWebhookEvent =
+  | Webhook<'directoryGroupMembership.created', DirectoryGroupMembershipWebhookEventJSON>
+  | Webhook<'directoryGroupMembership.deleted', DeletedDirectoryGroupMembershipWebhookEventJSON>;
+
 export type SessionWebhookEvent = Webhook<
   'session.created' | 'session.ended' | 'session.removed' | 'session.revoked',
   SessionWebhookEventJSON
@@ -140,6 +152,8 @@ export type WebhookEvent =
   | EmailWebhookEvent
   | EmailDeliveryWebhookEvent
   | SMSWebhookEvent
+  | DirectoryGroupWebhookEvent
+  | DirectoryGroupMembershipWebhookEvent
   | OrganizationWebhookEvent
   | OrganizationDomainWebhookEvent
   | OrganizationMembershipWebhookEvent

packages/backend/src/index.ts

@@ -103,6 +103,9 @@ export type {
   SMSMessageJSON,
   UserJSON,
   UserDeletedJSON,
+  DirectoryGroupWebhookEventJSON,
+  DirectoryGroupMembershipWebhookEventJSON,
+  DeletedDirectoryGroupMembershipWebhookEventJSON,
   VerificationJSON,
   WaitlistEntryJSON,
   Web3WalletJSON,
@@ -184,6 +187,8 @@ export type {
   PermissionWebhookEvent,
   SessionWebhookEvent,
   SMSWebhookEvent,
+  DirectoryGroupWebhookEvent,
+  DirectoryGroupMembershipWebhookEvent,
   UserWebhookEvent,
   WaitlistEntryWebhookEvent,
   WebhookEvent,