Merge pull request #206 from hypercerts-org/feat/resend-webhook-additional-events

auth: expand Resend email event handling

Author: aspiers

.changeset/resend-delivery-webhooks.md

@@ -6,4 +6,4 @@ Optional email-event logging for operators who choose the third-party Resend ser
 
 **Affects:** Operators
 
-**Operators:** ePDS remains compatible with any SMTP provider and does not require Resend. Operators who already use Resend can opt in by registering `https://<AUTH_HOSTNAME>/webhooks/resend` for the documented email events and setting `RESEND_WEBHOOK_SECRET`; optional Resend open tracking adds `opened` logs. The route verifies each webhook, logs only events whose sender exactly matches `SMTP_FROM`, and does not persist webhook data.
+**Operators:** ePDS remains compatible with any SMTP provider and does not require Resend. Operators who already use Resend can opt in by registering `https://<AUTH_HOSTNAME>/webhooks/resend` for the documented email events and setting `RESEND_WEBHOOK_SECRET`; logs include delivery, open, complaint, suppression, and scheduling events. The route verifies each webhook, logs only events whose sender exactly matches `SMTP_FROM`, acknowledges unsupported click and inbound events without logging their payloads, and does not persist webhook data.

docs/configuration.md

@@ -213,7 +213,8 @@ To opt into email-event logging for email sent through Resend:
 
 1. In the Resend dashboard, register `https://<AUTH_HOSTNAME>/webhooks/resend`.
 2. Subscribe it to `email.sent`, `email.delivered`, `email.delivery_delayed`,
-   `email.opened`, `email.bounced`, and `email.failed`.
+   `email.opened`, `email.bounced`, `email.failed`, `email.complained`,
+   `email.suppressed`, and `email.scheduled`.
 3. To receive `email.opened`, enable Resend open tracking for the sending domain
    and configure its tracking CNAME. Resend inserts the tracking pixel; ePDS
    does not alter email HTML. Without tracking, the other events still work.
@@ -237,10 +238,14 @@ a provider-neutral log schema: `provider`, `eventId`, `eventType`, `occurredAt`,
 `messageId`, `email`, and `subject`. Any sign-in code in `subject` is replaced
 with `[REDACTED]` to prevent it from reaching logs while preserving the rest of
 the subject. Resend event types are normalized to `sent`, `delivered`, `delayed`,
-`opened`, `bounced`, or `failed`. Normal events use `info`; `delayed` uses
-`warn`. An `opened` event means the tracking pixel was fetched, which can be
-caused or suppressed by mail-client privacy features and is not proof that the
-recipient read the message. No webhook data is persisted by ePDS. The
+`opened`, `bounced`, `failed`, `complained`, `suppressed`, or `scheduled`.
+`Delayed`, `complained`, and `suppressed` events use `warn`; the rest use `info`.
+An `opened` event means the tracking pixel was fetched, which can be caused or
+suppressed by mail-client privacy features and is not proof that the recipient
+read the message. Signed `email.clicked` and inbound `email.received` events are
+acknowledged without logging their payloads, preventing retries if the Resend
+endpoint is accidentally subscribed to them. No webhook data is persisted by
+ePDS. The
 provider-specific rate limit permits 300 webhook requests per minute per source
 IP.
 

docs/design/testing-gaps.md

@@ -15,7 +15,7 @@ pds-core callback, full OAuth flow).
 | `auth-service/lib/`           | ~77%     | `auto-provision.ts` at 0% (needs live PDS)                             |
 | `auth-service/middleware/`    | ~91%     | `rate-limit.ts` timer cleanup at 82%                                   |
 | `auth-service/email/`         | ~71%     | Template conditional branches partially covered                        |
-| `auth-service/routes/`        | ~32%     | Resend webhook is HTTP-tested; browser/OAuth routes remain gaps        |
+| `auth-service/routes/`        | ~35%     | Resend webhook is HTTP-tested; browser/OAuth routes remain gaps        |
 | `auth-service/better-auth.ts` | 0%       | better-auth wiring — see below                                         |
 | `auth-service/context.ts`     | 0%       | Minimal glue class                                                     |
 | `auth-service/index.ts`       | 0%       | Express app assembly + `main()`                                        |
@@ -60,9 +60,9 @@ pds-core callback, full OAuth flow).
 ### 2. `auth-service/src/routes/` (low coverage)
 
 The signed `resend-webhook.ts` receiver has HTTP-level integration coverage
-for valid signatures, rejected signatures, supported event filtering,
-structured logging, and retry correlation. The browser/OAuth route files remain the
-main gap: `login-page.ts`, `consent.ts`, `recovery.ts`, `account-login.ts`,
+for valid signatures, rejected signatures, logged and ignored event filtering,
+structured logging, and retry correlation. The browser/OAuth route files remain
+this area's main gap: `login-page.ts`, `consent.ts`, `recovery.ts`, `account-login.ts`,
 `account-settings.ts`, `choose-handle.ts`, and `complete.ts`.
 
 **Why they're hard:**

packages/auth-service/.env.example

@@ -141,7 +141,8 @@ SMTP_FROM_NAME=ePDS
 # Resend users only (optional). ePDS supports any SMTP provider and does not
 # require Resend. To opt into Resend email event logs, register
 # https://<AUTH_HOSTNAME>/webhooks/resend for email.sent, email.delivered,
-# email.delivery_delayed, email.opened, email.bounced, and email.failed, then set:
+# email.delivery_delayed, email.opened, email.bounced, email.failed,
+# email.complained, email.suppressed, and email.scheduled, then set:
 # RESEND_WEBHOOK_SECRET=whsec_...
 # Account-wide Resend events are filtered to the exact SMTP_FROM address.
 

packages/auth-service/src/__tests__/resend-webhook.test.ts

@@ -123,14 +123,17 @@ describe('Resend webhook receiver', () => {
     )
   })
 
-  it('normalizes open-tracking events', async () => {
-    const result = await postWebhook(makeEvent('email.opened'))
+  it.each([
+    ['email.opened', 'opened'],
+    ['email.scheduled', 'scheduled'],
+  ])('normalizes %s events as %s', async (resendType, normalizedType) => {
+    const result = await postWebhook(makeEvent(resendType))
 
     expect(result).toEqual({ status: 200, json: { received: true } })
     expect(logInfo).toHaveBeenCalledWith(
       expect.objectContaining({
         provider: 'resend',
-        eventType: 'opened',
+        eventType: normalizedType,
         messageId: 'resend-email-123',
         email: 'person@example.com',
       }),
@@ -205,14 +208,18 @@ describe('Resend webhook receiver', () => {
     )
   })
 
-  it('logs delivery delays at warning level', async () => {
-    await postWebhook(makeEvent('email.delivery_delayed'))
+  it.each([
+    ['email.delivery_delayed', 'delayed'],
+    ['email.complained', 'complained'],
+    ['email.suppressed', 'suppressed'],
+  ])('logs %s as %s at warning level', async (resendType, normalizedType) => {
+    await postWebhook(makeEvent(resendType))
 
     expect(logWarn).toHaveBeenCalledWith(
       expect.objectContaining({
         provider: 'resend',
         eventId: 'msg_test_123',
-        eventType: 'delayed',
+        eventType: normalizedType,
         messageId: 'resend-email-123',
       }),
       'Received email event',
@@ -237,8 +244,30 @@ describe('Resend webhook receiver', () => {
     expect(logInfo).not.toHaveBeenCalled()
   })
 
-  it('rejects signed event types that are not used for email logs', async () => {
-    const result = await postWebhook(makeEvent('email.received'))
+  it.each(['email.clicked', 'email.received'])(
+    'acknowledges ignored %s events without logging their payload',
+    async (eventType) => {
+      const result = await postWebhook(makeEvent(eventType))
+
+      expect(result).toEqual({
+        status: 200,
+        json: { received: true, ignored: true },
+      })
+      expect(logInfo).not.toHaveBeenCalled()
+      expect(logWarn).not.toHaveBeenCalled()
+      expect(logDebug).toHaveBeenCalledWith(
+        {
+          provider: 'resend',
+          eventId: 'msg_test_123',
+          eventType: eventType.slice('email.'.length),
+        },
+        'Ignored unsupported email webhook event',
+      )
+    },
+  )
+
+  it('rejects unknown signed event types', async () => {
+    const result = await postWebhook(makeEvent('email.unknown'))
 
     expect(result.status).toBe(400)
     expect(result.json).toEqual({ error: 'Invalid webhook payload' })

packages/auth-service/src/routes/resend-webhook.ts

@@ -17,15 +17,31 @@ const logger = createLogger('auth:email-webhook')
 
 export const RESEND_WEBHOOK_PATH = '/webhooks/resend'
 
-const RESEND_EVENT_TYPES = [
+const LOGGED_RESEND_EVENT_TYPES = [
   'email.sent',
   'email.delivered',
   'email.delivery_delayed',
   'email.opened',
   'email.bounced',
   'email.failed',
+  'email.complained',
+  'email.suppressed',
+  'email.scheduled',
 ] as const
 
+const IGNORED_RESEND_EVENT_TYPES = ['email.clicked', 'email.received'] as const
+const RESEND_EVENT_TYPES = [
+  ...LOGGED_RESEND_EVENT_TYPES,
+  ...IGNORED_RESEND_EVENT_TYPES,
+] as const
+
+const WARNING_RESEND_EVENT_TYPES = [
+  'email.delivery_delayed',
+  'email.complained',
+  'email.suppressed',
+] as const
+
+type LoggedResendEventType = (typeof LOGGED_RESEND_EVENT_TYPES)[number]
 type ResendEventType = (typeof RESEND_EVENT_TYPES)[number]
 type EmailEventType =
   | 'sent'
@@ -34,15 +50,21 @@ type EmailEventType =
   | 'opened'
   | 'bounced'
   | 'failed'
+  | 'complained'
+  | 'suppressed'
+  | 'scheduled'
 type OtpCharset = 'numeric' | 'alphanumeric'
 
-const NORMALIZED_EVENT_TYPES: Record<ResendEventType, EmailEventType> = {
+const NORMALIZED_EVENT_TYPES: Record<LoggedResendEventType, EmailEventType> = {
   'email.sent': 'sent',
   'email.delivered': 'delivered',
   'email.delivery_delayed': 'delayed',
   'email.opened': 'opened',
   'email.bounced': 'bounced',
   'email.failed': 'failed',
+  'email.complained': 'complained',
+  'email.suppressed': 'suppressed',
+  'email.scheduled': 'scheduled',
 }
 
 interface ResendEvent {
@@ -190,8 +212,14 @@ function redactOtpFromSubject(
   )
 }
 
-function logResendEvent(
+function isLoggedResendEvent(
   event: ResendEvent,
+): event is ResendEvent & { type: LoggedResendEventType } {
+  return (LOGGED_RESEND_EVENT_TYPES as readonly string[]).includes(event.type)
+}
+
+function logResendEvent(
+  event: ResendEvent & { type: LoggedResendEventType },
   svixId: string,
   otpLength: number,
   otpCharset: OtpCharset,
@@ -206,7 +234,7 @@ function logResendEvent(
     subject: redactOtpFromSubject(event.data.subject, otpLength, otpCharset),
   }
   const message = 'Received email event'
-  if (event.type === 'email.delivery_delayed') {
+  if ((WARNING_RESEND_EVENT_TYPES as readonly string[]).includes(event.type)) {
     logger.warn(fields, message)
   } else {
     logger.info(fields, message)
@@ -237,6 +265,19 @@ export function createResendWebhookRouter(
       }
 
       const eventId = result.headers['svix-id']
+      if (!isLoggedResendEvent(result.event)) {
+        logger.debug(
+          {
+            provider: 'resend',
+            eventId,
+            eventType: result.event.type.slice('email.'.length),
+          },
+          'Ignored unsupported email webhook event',
+        )
+        res.status(200).json({ received: true, ignored: true })
+        return
+      }
+
       const eventFromAddress = parseSingleEmailAddress(result.event.data.from)
       if (eventFromAddress !== expectedFromAddress) {
         logger.debug(

vitest.config.ts

@@ -26,7 +26,7 @@ export default defineConfig({
         statements: 58,
         branches: 57,
         functions: 71,
-        lines: 56,
+        lines: 57,
       },
     },
   },