feat(backend): add transactional email outcome webhook types

.changeset/friendly-email-outcomes.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Add webhook types for transactional email delivery, delays, bounces, complaints, failures, and suppressions. Bounce events distinguish `Permanent`, `Transient`, and `Undetermined` classifications. `verifyWebhook()` preserves the original event timestamp and instance ID for outcome handlers. These types prepare for the transactional email pilot; receiving the events requires the corresponding backend rollout.

packages/backend/src/__tests__/email-outcomes.test.ts

@@ -0,0 +1,45 @@
+import { describe, expectTypeOf, test } from 'vitest';
+
+import type { EmailBounceType, EmailDeliveryWebhookEvent, EmailWebhookEvent, WebhookEvent } from '../index';
+import type { verifyWebhook } from '../webhooks';
+
+describe('transactional email outcome webhooks', () => {
+  test('preserves the common resource ID used by existing webhook handlers', () => {
+    type VerifiedEvent = Awaited<ReturnType<typeof verifyWebhook>>;
+    expectTypeOf<VerifiedEvent['data']['id']>().toEqualTypeOf<string | undefined>();
+    expectTypeOf<EmailDeliveryWebhookEvent['data']['id']>().toEqualTypeOf<string>();
+    expectTypeOf<VerifiedEvent['event_attributes']>().toEqualTypeOf<EmailWebhookEvent['event_attributes']>();
+  });
+
+  test('narrows the bounce classification', () => {
+    type Bounced = Extract<Awaited<ReturnType<typeof verifyWebhook>>, { type: 'email.bounced' }>;
+    expectTypeOf<Bounced['data']['bounce']['type']>().toEqualTypeOf<EmailBounceType>();
+    expectTypeOf<Bounced['data']['to']>().toEqualTypeOf<[string]>();
+    expectTypeOf<Bounced['timestamp']>().toEqualTypeOf<number>();
+    expectTypeOf<Bounced['event_attributes']>().toEqualTypeOf<EmailWebhookEvent['event_attributes']>();
+  });
+
+  test('keeps existing email.created types separate', () => {
+    expectTypeOf<EmailWebhookEvent['type']>().toEqualTypeOf<'email.created'>();
+    expectTypeOf<EmailDeliveryWebhookEvent>().toExtend<WebhookEvent>();
+  });
+
+  test('distinguishes Clerk policy suppression from provider suppression', () => {
+    type Suppressed = Extract<EmailDeliveryWebhookEvent, { type: 'email.suppressed' }>;
+    type Policy = Extract<Suppressed['data']['suppressed'], { type: 'ClerkPolicy' }>;
+    expectTypeOf<Policy['reason']>().toEqualTypeOf<
+      'unverified_email_dns' | 'provider_domain_restriction' | 'application_communication_lock'
+    >();
+    type Failed = Extract<EmailDeliveryWebhookEvent, { type: 'email.failed' }>;
+    expectTypeOf<Failed['data']['failed']['reason']>().toEqualTypeOf<
+      'provider_rejected' | 'delivery_retry_exhausted' | 'send_retry_exhausted'
+    >();
+  });
+
+  test('requires explicit bounce classification', () => {
+    type Bounced = Extract<EmailDeliveryWebhookEvent, { type: 'email.bounced' }>;
+    // @ts-expect-error A failed send does not establish a permanent bounce.
+    const bounce: Bounced['data']['bounce'] = { type: 'failed', message: 'Failed to send' };
+    expectTypeOf(bounce).toEqualTypeOf<Bounced['data']['bounce']>();
+  });
+});

packages/backend/src/__tests__/webhooks.test.ts

@@ -1,6 +1,7 @@
 import { Webhook } from 'standardwebhooks';
 import { beforeEach, describe, expect, it } from 'vitest';
 
+import type { EmailDeliveryWebhookEvent } from '../api/resources/Webhooks';
 import { verifyWebhook } from '../webhooks';
 
 describe('verifyWebhook', () => {
@@ -18,6 +19,34 @@ describe('verifyWebhook', () => {
     return webhook.sign(id, new Date(parseInt(timestamp) * 1000), body);
   };
 
+  it('preserves a signed email outcome and its original event time', async () => {
+    const event: EmailDeliveryWebhookEvent = {
+      object: 'event',
+      type: 'email.bounced',
+      timestamp: 1789387200123,
+      instance_id: 'ins_example',
+      event_attributes: { http_request: { client_ip: '', user_agent: '' } },
+      data: {
+        id: 'ema_example',
+        to: ['recipient@example.com'],
+        bounce: { type: 'Permanent', message: 'Unknown mailbox' },
+      },
+    };
+    const body = JSON.stringify(event);
+    const id = 'msg_outcome';
+    const timestamp = Math.floor(Date.now() / 1000).toString();
+    const request = new Request('https://example.com/webhooks', {
+      method: 'POST',
+      body,
+      headers: {
+        'svix-id': id,
+        'svix-timestamp': timestamp,
+        'svix-signature': createValidSignature(id, timestamp, body),
+      },
+    });
+    expect(await verifyWebhook(request)).toEqual(event);
+  });
+
   it('throws when required headers are missing', async () => {
     const mockRequest = new Request('https://clerk.com/webhooks', {
       method: 'POST',

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

@@ -33,6 +33,37 @@ export type UserWebhookEvent =
 
 export type EmailWebhookEvent = Webhook<'email.created', EmailJSON>;
 
+export type EmailBounceType = 'Permanent' | 'Transient' | 'Undetermined';
+
+type EmailOutcomeWebhook<Type, Details = unknown> = {
+  object: 'event';
+  type: Type;
+  timestamp: number;
+  instance_id: string;
+  event_attributes: WebhookEventAttributes;
+  data: { id: string; to: [string] } & Details;
+};
+
+export type EmailDeliveryWebhookEvent =
+  | EmailOutcomeWebhook<'email.delivered' | 'email.delivery_delayed' | 'email.complained'>
+  | EmailOutcomeWebhook<'email.bounced', { bounce: { type: EmailBounceType; message: string } }>
+  | EmailOutcomeWebhook<
+      'email.failed',
+      { failed: { reason: 'provider_rejected' | 'delivery_retry_exhausted' | 'send_retry_exhausted' } }
+    >
+  | EmailOutcomeWebhook<
+      'email.suppressed',
+      {
+        suppressed:
+          | { type: 'OnProviderSuppressionList'; message: string }
+          | {
+              type: 'ClerkPolicy';
+              reason: 'unverified_email_dns' | 'provider_domain_restriction' | 'application_communication_lock';
+              message: string;
+            };
+      }
+    >;
+
 export type SMSWebhookEvent = Webhook<'sms.created', SMSMessageJSON>;
 
 export type SessionWebhookEvent = Webhook<
@@ -100,6 +131,7 @@ export type WebhookEvent =
   | UserWebhookEvent
   | SessionWebhookEvent
   | EmailWebhookEvent
+  | EmailDeliveryWebhookEvent
   | SMSWebhookEvent
   | OrganizationWebhookEvent
   | OrganizationDomainWebhookEvent

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

@@ -70,6 +70,8 @@ export * from './Web3Wallet';
 
 export type {
   EmailWebhookEvent,
+  EmailBounceType,
+  EmailDeliveryWebhookEvent,
   OrganizationDomainWebhookEvent,
   OrganizationInvitationAcceptedWebhookEvent,
   OrganizationInvitationWebhookEvent,

packages/backend/src/index.ts

@@ -173,6 +173,8 @@ export type {
  */
 export type {
   EmailWebhookEvent,
+  EmailBounceType,
+  EmailDeliveryWebhookEvent,
   OrganizationWebhookEvent,
   OrganizationDomainWebhookEvent,
   OrganizationInvitationAcceptedWebhookEvent,

packages/backend/src/webhooks.ts

@@ -135,6 +135,8 @@ export async function verifyWebhook(request: Request, options: VerifyWebhookOpti
       object: 'event',
       data: payload.data,
       event_attributes: payload.event_attributes,
+      timestamp: payload.timestamp,
+      instance_id: payload.instance_id,
     } as WebhookEvent;
   } catch (e) {
     return errorThrower.throw(`Unable to verify incoming webhook: ${e instanceof Error ? e.message : 'Unknown error'}`);