feat(auth): log Resend email open events

Operators using Resend open tracking could see delivery outcomes but not whether the message's tracking pixel was fetched.\n\nAccept email.opened webhooks, normalize them to opened, and document the required tracking opt-in and reliability caveats. The event uses the existing sender filter and sanitized provider-neutral log fields.\n\nFollow-up to #185.\n\nCo-authored-by: OpenAI <noreply@openai.com>

Author: aspiers

.changeset/resend-delivery-webhooks.md

@@ -2,8 +2,8 @@
 'ePDS': minor
 ---
 
-Optional delivery-event logging for operators who choose the third-party Resend service to send email; ePDS continues to support other email providers.
+Optional email-event logging for operators who choose the third-party Resend service to send email; ePDS continues to support other email providers.
 
 **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`; 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`; 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.

.env.example

@@ -214,9 +214,9 @@ SMTP_PASS=
 SMTP_FROM=noreply@pds.example
 SMTP_FROM_NAME=ePDS
 
-# Resend users only (optional): delivery webhook signing secret. ePDS supports
-# any SMTP provider and does not require Resend. To opt into Resend delivery
-# event logs, configure https://auth.pds.example/webhooks/resend and set:
+# Resend users only (optional): email webhook signing secret. ePDS supports
+# any SMTP provider and does not require Resend. To opt into Resend email event
+# logs, configure https://auth.pds.example/webhooks/resend and set:
 # RESEND_WEBHOOK_SECRET=whsec_...
 # Account-wide Resend events are filtered to the exact SMTP_FROM address.
 

docs/configuration.md

@@ -198,24 +198,30 @@ buttons appear on the login page.
 | `POSTMARK_SERVER_TOKEN`          | Postmark server token                                                                                                                                                                                                  |
 | `EMAIL_TEMPLATE_ALLOWED_DOMAINS` | Optional comma-separated list of HTTPS hostnames from which `email_template_uri` can be fetched. If unset, any HTTPS URL is allowed. If set, templates hosted on unlisted domains are logged as a warning and ignored. |
 
-#### Optional Resend delivery event logs
+#### Optional Resend email event logs
 
 ePDS does **not** require Resend: operators can use any SMTP provider. This
 provider-specific integration is only for operators who already send through
-Resend and choose to log its delivery webhooks. Without
+Resend and choose to log its email webhooks. Without
 `RESEND_WEBHOOK_SECRET`, the webhook route is not mounted.
 
 | Variable                | Description                                                                                                                                           |
 | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `RESEND_WEBHOOK_SECRET` | Resend users only. Optional webhook signing secret (`whsec_...`) that enables `POST /webhooks/resend` and structured Resend event logs when provided. |
 
-To opt into delivery-event logging for email sent through Resend:
+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.bounced`, and `email.failed`.
-3. Set `RESEND_WEBHOOK_SECRET` to that endpoint's signing secret and redeploy the auth service.
-4. Send a test sign-in code through the production SMTP configuration and
-   confirm that both `email.sent` and `email.delivered` reach the receiver.
+2. Subscribe it to `email.sent`, `email.delivered`, `email.delivery_delayed`,
+   `email.opened`, `email.bounced`, and `email.failed`.
+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.
+4. Set `RESEND_WEBHOOK_SECRET` to that endpoint's signing secret and redeploy
+   the auth service.
+5. Send a test sign-in code through the production SMTP configuration and
+   confirm that `email.sent` and `email.delivered` reach the receiver. If open
+   tracking is enabled, open the message and confirm `email.opened` also arrives.
    Resend's documentation does not explicitly guarantee that SMTP-submitted
    email emits webhooks, so verify this before relying on the logs.
 
@@ -231,8 +237,10 @@ 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`,
-`bounced`, or `failed`. Normal events use `info`;
-`delayed` uses `warn`. No webhook data is persisted by ePDS. The
+`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
 provider-specific rate limit permits 300 webhook requests per minute per source
 IP.
 

packages/auth-service/.env.example

@@ -139,9 +139,9 @@ SMTP_FROM=noreply@pds.example
 SMTP_FROM_NAME=ePDS
 
 # Resend users only (optional). ePDS supports any SMTP provider and does not
-# require Resend. To opt into Resend delivery event logs, register
+# require Resend. To opt into Resend email event logs, register
 # https://<AUTH_HOSTNAME>/webhooks/resend for email.sent, email.delivered,
-# email.delivery_delayed, email.bounced, and email.failed, then set:
+# email.delivery_delayed, email.opened, email.bounced, and email.failed, 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

@@ -119,7 +119,22 @@ describe('Resend webhook receiver', () => {
         email: 'person@example.com',
         subject: '[REDACTED] — Your sign-in code',
       },
-      'Received email delivery event',
+      'Received email event',
+    )
+  })
+
+  it('normalizes open-tracking events', async () => {
+    const result = await postWebhook(makeEvent('email.opened'))
+
+    expect(result).toEqual({ status: 200, json: { received: true } })
+    expect(logInfo).toHaveBeenCalledWith(
+      expect.objectContaining({
+        provider: 'resend',
+        eventType: 'opened',
+        messageId: 'resend-email-123',
+        email: 'person@example.com',
+      }),
+      'Received email event',
     )
   })
 
@@ -200,7 +215,7 @@ describe('Resend webhook receiver', () => {
         eventType: 'delayed',
         messageId: 'resend-email-123',
       }),
-      'Received email delivery event',
+      'Received email event',
     )
   })
 
@@ -222,15 +237,15 @@ describe('Resend webhook receiver', () => {
     expect(logInfo).not.toHaveBeenCalled()
   })
 
-  it('rejects signed event types that are not used for delivery logs', async () => {
-    const result = await postWebhook(makeEvent('email.opened'))
+  it('rejects signed event types that are not used for email logs', async () => {
+    const result = await postWebhook(makeEvent('email.received'))
 
     expect(result.status).toBe(400)
     expect(result.json).toEqual({ error: 'Invalid webhook payload' })
     expect(logInfo).not.toHaveBeenCalled()
   })
 
-  it('rejects a delivery event without a recipient email', async () => {
+  it('rejects an email event without a recipient email', async () => {
     const event = makeEvent()
     const data = event.data as Record<string, unknown>
     data.to = []

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

@@ -1,12 +1,12 @@
 /**
- * Resend delivery webhook receiver.
+ * Resend email webhook receiver.
  *
  * The route consumes the untouched request body, verifies Resend's Svix
- * signature before inspecting the payload, accepts only delivery events used
- * by ePDS, and emits one structured log entry per delivery attempt. Resend may
- * retry the same source ID (logged as `eventId`) and may deliver an email's
- * events out of order, so log consumers must deduplicate and order events when
- * calculating latency.
+ * signature before inspecting the payload, accepts only email events used by
+ * ePDS, and emits one structured log entry per event. Resend may retry the same
+ * source ID (logged as `eventId`) and may deliver an email's events out of
+ * order, so log consumers must deduplicate and order events when calculating
+ * latency.
  */
 import express, { Router } from 'express'
 import addressparser from 'nodemailer/lib/addressparser/index.js'
@@ -21,27 +21,29 @@ const RESEND_EVENT_TYPES = [
   'email.sent',
   'email.delivered',
   'email.delivery_delayed',
+  'email.opened',
   'email.bounced',
   'email.failed',
 ] as const
 
 type ResendEventType = (typeof RESEND_EVENT_TYPES)[number]
-type EmailDeliveryEventType =
+type EmailEventType =
   | 'sent'
   | 'delivered'
   | 'delayed'
+  | 'opened'
   | 'bounced'
   | 'failed'
 type OtpCharset = 'numeric' | 'alphanumeric'
 
-const NORMALIZED_EVENT_TYPES: Record<ResendEventType, EmailDeliveryEventType> =
-  {
-    'email.sent': 'sent',
-    'email.delivered': 'delivered',
-    'email.delivery_delayed': 'delayed',
-    'email.bounced': 'bounced',
-    'email.failed': 'failed',
-  }
+const NORMALIZED_EVENT_TYPES: Record<ResendEventType, EmailEventType> = {
+  'email.sent': 'sent',
+  'email.delivered': 'delivered',
+  'email.delivery_delayed': 'delayed',
+  'email.opened': 'opened',
+  'email.bounced': 'bounced',
+  'email.failed': 'failed',
+}
 
 interface ResendEvent {
   type: ResendEventType
@@ -203,7 +205,7 @@ function logResendEvent(
     email: event.data.to[0],
     subject: redactOtpFromSubject(event.data.subject, otpLength, otpCharset),
   }
-  const message = 'Received email delivery event'
+  const message = 'Received email event'
   if (event.type === 'email.delivery_delayed') {
     logger.warn(fields, message)
   } else {