egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Resend inbound client and webhook endpoint (#149) #155

New Issue
Closed
opened 2026-02-13 03:51:53 +00:00 by egullickson · 1 comment
egullickson commented 2026-02-13 03:51:53 +00:00
Owner
Copy Link

Relates to #149

Scope

Create the webhook endpoint for receiving Resend inbound emails and the client for fetching email content.

Webhook Endpoint

  • POST /api/webhooks/resend/inbound (public, no JWT auth)
  • rawBody: true config for signature verification
  • Verify signature via resend.webhooks.verify()
  • Idempotency check: reject if email_id already exists in queue
  • Insert email_ingestion_queue row with status=pending
  • Return 200 immediately
  • Trigger async processing via setImmediate()

Resend Inbound Client

  • ResendInboundClient class in external/resend-inbound.client.ts
  • getEmail(emailId): Call resend.emails.receiving.get() to get raw.download_url
  • downloadRawEmail(downloadUrl): Download raw RFC 5322 email
  • parseEmail(rawEmail): Parse with mailparser to extract body text/html + attachments

Route Registration

  • Register in app.ts alongside existing webhook routes
  • Follow Stripe webhook pattern (no preHandler auth)

Environment

  • RESEND_WEBHOOK_SECRET env var for signature verification

Files

  • backend/src/features/email-ingestion/api/email-ingestion.routes.ts
  • backend/src/features/email-ingestion/api/email-ingestion.controller.ts
  • backend/src/features/email-ingestion/external/resend-inbound.client.ts
  • backend/src/features/email-ingestion/index.ts

Dependencies

  • mailparser + @types/mailparser

Acceptance Criteria

  • Webhook endpoint receives and verifies Resend signatures
  • Invalid signatures return 400
  • Duplicate email_ids are rejected (idempotent)
  • Raw email is fetched and parsed into body + attachments
  • 200 returned before processing begins
Relates to #149 ## Scope Create the webhook endpoint for receiving Resend inbound emails and the client for fetching email content. ### Webhook Endpoint - `POST /api/webhooks/resend/inbound` (public, no JWT auth) - `rawBody: true` config for signature verification - Verify signature via `resend.webhooks.verify()` - Idempotency check: reject if email_id already exists in queue - Insert `email_ingestion_queue` row with status=pending - Return 200 immediately - Trigger async processing via `setImmediate()` ### Resend Inbound Client - `ResendInboundClient` class in `external/resend-inbound.client.ts` - `getEmail(emailId)`: Call `resend.emails.receiving.get()` to get raw.download_url - `downloadRawEmail(downloadUrl)`: Download raw RFC 5322 email - `parseEmail(rawEmail)`: Parse with `mailparser` to extract body text/html + attachments ### Route Registration - Register in `app.ts` alongside existing webhook routes - Follow Stripe webhook pattern (no preHandler auth) ### Environment - `RESEND_WEBHOOK_SECRET` env var for signature verification ### Files - `backend/src/features/email-ingestion/api/email-ingestion.routes.ts` - `backend/src/features/email-ingestion/api/email-ingestion.controller.ts` - `backend/src/features/email-ingestion/external/resend-inbound.client.ts` - `backend/src/features/email-ingestion/index.ts` ### Dependencies - `mailparser` + `@types/mailparser` ## Acceptance Criteria - [ ] Webhook endpoint receives and verifies Resend signatures - [ ] Invalid signatures return 400 - [ ] Duplicate email_ids are rejected (idempotent) - [ ] Raw email is fetched and parsed into body + attachments - [ ] 200 returned before processing begins
egullickson added the
status
backlog
type
feature
 labels 2026-02-13 03:52:47 +00:00
egullickson added this to the Sprint 2026-02-02 milestone 2026-02-13 03:52:57 +00:00
egullickson added
status
in-progress
 and removed
status
backlog
 labels 2026-02-13 14:14:50 +00:00
egullickson commented 2026-02-13 14:22:42 +00:00
Author
Owner
Copy Link

Milestone: Resend Inbound Webhook Endpoint and Client

Phase: Execution | Agent: Developer | Status: PASS

Completed

Webhook Endpoint (POST /api/webhooks/resend/inbound):

  • Public endpoint (no JWT auth), rawBody enabled for signature verification
  • Svix-based signature verification using svix-id, svix-timestamp, svix-signature headers
  • Idempotency check: rejects duplicate email_id entries
  • Inserts email_ingestion_queue row with status=pending
  • Returns 200 immediately, triggers async processing via setImmediate()
  • Follows Stripe webhook route pattern

ResendInboundClient (external/resend-inbound.client.ts):

  • verifyWebhookSignature(): Svix webhook verification
  • getEmail(emailId): Fetches email metadata from Resend API
  • downloadRawEmail(downloadUrl): Downloads raw RFC 5322 email content
  • parseEmail(rawEmail): Parses with mailparser into text/html + attachments

Config (config-loader.ts):

  • Added resend_webhook_secret (optional) to secrets schema
  • Added getResendConfig() convenience accessor
  • Environment variable RESEND_WEBHOOK_SECRET set from secret file

Route Registration (app.ts):

  • Registered emailIngestionWebhookRoutes alongside Stripe webhooks
  • Added email-ingestion to health check feature list

Dependencies:

  • mailparser + @types/mailparser for RFC 5322 parsing
  • svix for Resend webhook signature verification

Validation

  • TypeScript type-check: PASS
  • ESLint: PASS (0 errors, 3 warnings - standard any type warnings matching existing patterns)
  • Tests: All 142 tests pass (pre-existing integration test failures unrelated to changes)

Files Changed

  • backend/src/features/email-ingestion/api/email-ingestion.routes.ts (new)
  • backend/src/features/email-ingestion/api/email-ingestion.controller.ts (new)
  • backend/src/features/email-ingestion/external/resend-inbound.client.ts (new)
  • backend/src/features/email-ingestion/index.ts (new)
  • backend/src/app.ts (modified - route registration)
  • backend/src/core/config/config-loader.ts (modified - resend webhook secret)
  • backend/package.json (modified - new dependencies)

Verdict: PASS | Next: Async processing pipeline (sender validation, OCR, record creation)

## Milestone: Resend Inbound Webhook Endpoint and Client **Phase**: Execution | **Agent**: Developer | **Status**: PASS ### Completed **Webhook Endpoint** (`POST /api/webhooks/resend/inbound`): - Public endpoint (no JWT auth), rawBody enabled for signature verification - Svix-based signature verification using `svix-id`, `svix-timestamp`, `svix-signature` headers - Idempotency check: rejects duplicate `email_id` entries - Inserts `email_ingestion_queue` row with status=pending - Returns 200 immediately, triggers async processing via `setImmediate()` - Follows Stripe webhook route pattern **ResendInboundClient** (`external/resend-inbound.client.ts`): - `verifyWebhookSignature()`: Svix webhook verification - `getEmail(emailId)`: Fetches email metadata from Resend API - `downloadRawEmail(downloadUrl)`: Downloads raw RFC 5322 email content - `parseEmail(rawEmail)`: Parses with mailparser into text/html + attachments **Config** (`config-loader.ts`): - Added `resend_webhook_secret` (optional) to secrets schema - Added `getResendConfig()` convenience accessor - Environment variable `RESEND_WEBHOOK_SECRET` set from secret file **Route Registration** (`app.ts`): - Registered `emailIngestionWebhookRoutes` alongside Stripe webhooks - Added `email-ingestion` to health check feature list **Dependencies**: - `mailparser` + `@types/mailparser` for RFC 5322 parsing - `svix` for Resend webhook signature verification ### Validation - TypeScript type-check: PASS - ESLint: PASS (0 errors, 3 warnings - standard `any` type warnings matching existing patterns) - Tests: All 142 tests pass (pre-existing integration test failures unrelated to changes) ### Files Changed - `backend/src/features/email-ingestion/api/email-ingestion.routes.ts` (new) - `backend/src/features/email-ingestion/api/email-ingestion.controller.ts` (new) - `backend/src/features/email-ingestion/external/resend-inbound.client.ts` (new) - `backend/src/features/email-ingestion/index.ts` (new) - `backend/src/app.ts` (modified - route registration) - `backend/src/core/config/config-loader.ts` (modified - resend webhook secret) - `backend/package.json` (modified - new dependencies) *Verdict*: PASS | *Next*: Async processing pipeline (sender validation, OCR, record creation)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
status
backlog
status/blocked
status
done
status
in-progress
status
ready
status
review
type
bug
type
chore
type
docs
type
feature
No Label
status
in-progress
type
feature
Milestone
No items
No Milestone Sprint 2026-02-02
Projects
Clear projects
No project
Assignees
Clear assignees
egullickson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: egullickson/motovaultpro#155
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?