Send ramp completion and verification outcome emails

[Sharqiewicz]

Users now get an email when a ramp completes and when their KYC/KYB verification is approved or rejected. Previously they had to sit on the page or check back manually.

Two emails, both bilingual (en-US / pt-BR, chosen from the user's locale):

• Ramp completed — amount, currency, network, ramp id
• Verification approved / rejected — outcome plus the provider's reason on rejection

How it works

Nothing sends mail inline. Every trigger just writes a row to a new email_notifications table, and a cron worker is the only sender:

trigger → enqueue row → dispatch worker (every minute) → Resend

That way a failed send never fails the thing that succeeded (a completed ramp, a verification), and nothing is lost if the API restarts mid-send.

• Triggers: PhaseProcessor on ramp complete; the Avenia webhook receiver; a KYB status poller (hourly) as a safety net in case a webhook never arrives.
• Dedupe: unique index on (provider, type, resource_id) — a replayed webhook or a re-polled attempt cannot double-send.
• Retries: claimed with FOR UPDATE SKIP LOCKED (safe with multiple backends), retried at 1/5/15/60/180 min, then abandoned with a Slack alert.
• Non-prod safety: outside DEPLOYMENT_ENV=production, any recipient not in EMAIL_RECIPIENT_ALLOWLIST is recorded as skipped and never emailed. Empty allowlist = nothing sends.

Recipient addresses always come from profiles.email for the notification's user — never from a request body or a partner-supplied field, so partner API ramps don't email anyone.

New: Avenia webhook receiver

POST /v1/webhooks/avenia, authenticated by Avenia's RSA-PSS signature over the raw body (mounted ahead of the JSON parser, since the signature covers the exact bytes). Their public key is cached an hour and
refetched once on a verification miss because they rotate it without notice. Register the subscription with bun register:avenia-webhook.

Deploying

Set these before merging to an environment that should actually send:

RESEND_API_KEY= # absent → rows stay queued, nothing sends, nothing lost
EMAIL_FROM_ADDRESS=Vortex Finance support@vortexfinance.co
AVENIA_WEBHOOK_URL= # only for the registration script

Also: one migration (055-create-email-notifications-table.ts), and vortexfinance.co needs to be verified in Resend before anything leaves.

[netlify]

✅ Deploy Preview for vortexfi ready!

Name	Link
🔨 Latest commit	de18eaf
🔍 Latest deploy log	https://app.netlify.com/projects/vortexfi/deploys/6a759c85a4ce930008f5cf79
😎 Deploy Preview	https://deploy-preview-1295--vortexfi.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[netlify]

✅ Deploy Preview for vrtx-dashboard canceled.

Name	Link
🔨 Latest commit	de18eaf
🔍 Latest deploy log	https://app.netlify.com/projects/vrtx-dashboard/deploys/6a759c856c5ede0008f269cc

[netlify]

✅ Deploy Preview for vortex-sandbox ready!

Name	Link
🔨 Latest commit	de18eaf
🔍 Latest deploy log	https://app.netlify.com/projects/vortex-sandbox/deploys/6a759c856c5ede0008f269ca
😎 Deploy Preview	https://deploy-preview-1295--vortex-sandbox.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

🟡 Not ready to approve

Queue durability, retry limits, opt-out handling, KYC copy, and KYB reconciliation contain unresolved correctness and reliability issues.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Adds durable, localized email notifications for ramp completion and Avenia verification outcomes, delivered asynchronously through Resend.

Changes:

• Adds the email queue, dispatcher, templates, retries, and Resend transport.
• Adds signed Avenia webhooks plus KYB polling reconciliation.
• Adds configuration, migration, tests, scripts, and security documentation.

File summaries

File	Description
supabase/config.toml	Documents local Resend SMTP setup.
packages/shared/src/services/brla/types.ts	Adds webhook and verification types.
packages/shared/src/services/brla/mappings.ts	Maps Avenia webhook endpoints.
packages/shared/src/services/brla/brlaApiService.ts	Adds webhook and key APIs.
docs/security-spec/README.md	Indexes the Resend specification.
docs/security-spec/05-integrations/resend.md	Defines email security invariants.
docs/security-spec/05-integrations/brla.md	Documents webhook security behavior.
docs/features/alfredpay-kyc-notification-gap.md	Records the Alfredpay follow-up.
docs/architecture/email-notifications.md	Describes notification architecture.
apps/api/src/scripts/register-avenia-webhook.ts	Registers Avenia webhooks.
apps/api/src/scripts/preview-emails.ts	Generates transactional previews.
apps/api/src/scripts/auth-email-templates.ts	Generates Supabase templates.
apps/api/src/models/kycCase.model.ts	Adds the entity association helper.
apps/api/src/models/index.ts	Registers notification associations.
apps/api/src/models/emailNotification.model.ts	Defines queued-email records.
apps/api/src/index.ts	Starts notification workers.
apps/api/src/database/migrations/055-create-email-notifications-table.ts	Creates the queue table.
apps/api/src/config/vars.ts	Adds email and webhook configuration.
apps/api/src/config/express.ts	Mounts the raw-body webhook route.
apps/api/src/api/workers/notification-dispatch.worker.ts	Schedules queued delivery.
apps/api/src/api/workers/kyb-status.worker.ts	Reconciles KYB outcomes.
apps/api/src/api/services/phases/phase-processor.ts	Triggers completion notifications.
apps/api/src/api/services/email/types.ts	Defines locales and payloads.
apps/api/src/api/services/email/templates/verification-status.ts	Renders verification emails.
apps/api/src/api/services/email/templates/ramp-completed.ts	Renders completion emails.
apps/api/src/api/services/email/templates/layout.ts	Provides the shared layout.
apps/api/src/api/services/email/templates/index.ts	Dispatches template rendering.
apps/api/src/api/services/email/resend.transport.ts	Sends mail through Resend.
apps/api/src/api/services/email/ramp-completion.ts	Builds completion payloads.
apps/api/src/api/services/email/notification.service.ts	Implements queue processing.
apps/api/src/api/services/email/index.ts	Exports email services.
apps/api/src/api/services/avenia/webhook-signature.ts	Verifies webhook signatures.
apps/api/src/api/services/avenia/webhook-signature.test.ts	Tests signature verification.
apps/api/src/api/services/avenia/verification-notifications.ts	Maps terminal outcomes.
apps/api/src/api/services/avenia/avenia-customer.service.ts	Resolves notification owners.
apps/api/src/api/services/avenia/__tests__/fixtures.ts	Provides cryptographic fixtures.
apps/api/src/api/services/auth/supabase.service.ts	Resolves user email locale.
apps/api/src/api/routes/v1/avenia-webhook.route.ts	Defines the webhook endpoint.
apps/api/src/api/controllers/brla.controller.ts	Persists KYB attempt IDs.
apps/api/src/api/controllers/avenia-webhook.controller.ts	Handles signed events.
apps/api/src/api/controllers/avenia-webhook.controller.test.ts	Tests webhook handling.
apps/api/package.json	Adds email utility scripts.
apps/api/.gitignore	Ignores generated previews.
apps/api/.env.example	Documents required variables.

Review details

Comments suppressed due to low confidence (5)

apps/api/src/api/services/email/notification.service.ts:96

• Delivery ignores the existing notification_preferences.email_enabled setting, so a user who explicitly disables email through the preferences API still receives these notifications. Check the profile's global email preference (and the relevant per-type preference, if applicable) before rendering/sending, and record opted-out rows as skipped.

async function deliver(notification: EmailNotification): Promise<void> {
  const user = await User.findByPk(notification.userId);

apps/api/src/api/services/email/notification.service.ts:119

• The database claim prevents concurrent workers from sending simultaneously, but it does not prevent a duplicate when Resend accepts the request and the process dies (or the following DB update fails) before Sent is persisted. Stale-claim recovery will send the same row again. Pass a deterministic provider idempotency key derived from notification.id through the transport so retries cannot create a second email.

  const messageId = await sendEmail({ ...rendered, to: user.email });

apps/api/src/api/services/email/notification.service.ts:153

• Every stale claim is reset to failed regardless of its attempt count, while the claim query has no attempts < MAX_ATTEMPTS guard. A process that repeatedly dies during the fifth send can therefore be claimed for attempts 6, 7, and beyond and never reaches abandoned or triggers the Slack alert. Mark stale rows at the cap as abandoned/alerted and only retry rows below the cap.

    { nextAttemptAt: new Date(), status: NotificationStatus.Failed },

apps/api/src/api/workers/kyb-status.worker.ts:81

• A terminal provider response only enqueues mail; it never changes this case's pending status or otherwise excludes it from the next query. Unless the user separately calls the status endpoint, the worker polls the same settled attempt every hour for up to 60 days. Persist the provider-confirmed terminal state after enqueueing, or exclude attempts that already have a terminal notification.

          await enqueueVerificationNotification(attempt, profileId);

apps/api/src/api/services/email/notification.service.ts:163

• The core queue state machine has no automated coverage: claiming/locking, allowlist skips, missing-key behavior, backoff/exhaustion, and stale-claim recovery can regress without detection. Add focused service tests, including a stale fifth attempt and a send accepted before persistence, since these are the feature's reliability guarantees.

export async function dispatchPendingNotifications(): Promise<void> {

• Files reviewed: 44/45 changed files
• Comments generated: 6
• Review effort level: Medium

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Changes recommended

Delivery idempotency, retry limits, provider validation, preference enforcement, and worker-bounding issues remain unresolved.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (14)

apps/api/src/api/workers/kyb-status.worker.ts:83

• Validate that Avenia returned the requested attempt before notifying. This worker currently accepts any attempt.id, so a malformed/misrouted provider response can send another attempt's outcome and rejection reason to this case's profile. The authenticated status path already rejects this at brla.controller.ts:868-871; apply the same check here.
  apps/api/src/api/workers/kyb-status.worker.ts:52
• Settled unattended cases remain selected every hour: this worker enqueues the email but deliberately never updates KycCase.status, and deduplication only suppresses another row, not another provider request. A terminal case can therefore be polled roughly 1,440 times over the 60-day window; additionally this findAll is unbounded. Exclude attempt IDs that already have a verification notification (or persist an observation marker) and cap each sweep.
  packages/shared/src/services/brla/brlaApiService.ts:426
• This fetch has no timeout. On a cold cache or signature miss, the public webhook awaits it, and all concurrent verifications coalesce onto the same potentially hung promise; an Avenia/network stall can therefore hold webhook connections for minutes and block key refresh. Add an abort timeout consistent with other provider clients.
  apps/api/src/api/services/email/ramp-completion.ts:39
• This records enqueue time, not completion time. The recovery sweep can run up to 24 hours after the ramp completed, so recovered emails show a materially incorrect date. Read the complete entry's timestamp from phaseHistory (and select that field in the reconciliation query), with updatedAt only as a legacy fallback.

      completedAt: new Date().toISOString(),

apps/api/src/api/workers/alfredpay-status.worker.ts:30

• This hourly job can overlap itself during a provider outage. A cycle may perform up to 750 sequential calls, each with a 30-second Alfredpay timeout, while this CronJob leaves waitForCompletion disabled; later hourly ticks then poll the same nonterminal accounts concurrently. Enable overlap prevention/a running guard and choose a batch size that finishes within the schedule interval.
  docs/architecture/email-notifications.md:4
• This new one-file docs/architecture/ tree conflicts with docs/README.md:8-15,55-69, which requires general architecture documents directly under docs/, indexed there, and warns against duplicating security-spec content and implementation inventories. Move this to a supported docs/architecture-*.md location, trim duplicated canonical material, update its links, and add it to the index.
  docs/features/alfredpay-kyc-notification-gap.md:4
• This one-off follow-up file violates the documentation lifecycle in docs/README.md:55-76: general docs belong at the root under a supported kind, and completed implementation summaries/open-gap journals should not be retained as standalone feature files. Fold the durable locale gap into the canonical product/architecture document or an explicitly scoped proposal, then remove this file and update links.
  docs/architecture/email-notifications.md:304
• The lifecycle diagram is off by one relative to the implementation and the preceding table: attempt 5 schedules the 180-minute retry, and attempt 6 is abandoned. As written, this architecture document says the final backoff is never used.
  docs/security-spec/05-integrations/brla.md:118
• These additions restart numbering at 25 even though invariant 25 is immediately above, making references ambiguous. Renumber the webhook invariants 26–29.
  apps/api/src/api/services/email/notification.service.ts:175
• The dispatcher's tests cover only nextRetryAt; none exercise claiming/locking, stale recovery, missing-key handling, allowlist enforcement, delivery state transitions, or concurrent workers. These are the feature's load-bearing security and reliability invariants, and the uncapped crash retry and uncertain-send duplicate paths currently pass unnoticed. Add database-backed dispatch tests covering success, failure, crash recovery, and concurrent claims.

export async function dispatchPendingNotifications(): Promise<void> {
  if (!config.integrations.resend.apiKey) {
    logger.warn("RESEND_API_KEY is not set; leaving pending notifications queued");
    return;
  }

apps/api/src/api/services/email/templates/ramp-completed.ts:48

• The linked acceptance ticket #1144 specifies a personalized Hi Name, greeting (and sign-off), but this template starts directly with the transaction body and the new architecture document explicitly defers the greeting. Either implement a trusted name source now or clarify with the ticket owner that this acceptance criterion is intentionally removed before marking the feature ready.

  const body: EmailBody = {
    details: [

docs/security-spec/05-integrations/resend.md:27

• This code map points auditors to the wrong producer: ramp.service.ts does not enqueue completion mail. The trigger is in phase-processor.ts, and payload construction/enqueueing is in email/ramp-completion.ts; list those paths so the audit checklist traces the real side effect.
  docs/architecture/email-notifications.md:94
• “All fire-and-forget” is incorrect and obscures important failure semantics: the webhook awaits enqueue before acknowledging, the KYB poll awaits it per attempt, and Alfredpay deliberately awaits it before persisting terminal status. Only ramp completion detaches the promise. Describe these as durable queue producers that never send inline instead.
  docs/architecture/email-notifications.md:195
• The diagram still names the removed TaxId.kycAttempt storage, while this PR's worker reads kyc_cases.provider_case_id. Update the state label so the architecture does not contradict the implementation described later in this section.

• Files reviewed: 54/55 changed files
• Comments generated: 4
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

Pull request overview

Copilot reviewed 71 out of 72 changed files in this pull request and generated 3 comments.

Suppressed comments (6)

apps/api/src/api/workers/kyb-status.worker.ts:74

• This excludes a KYB outcome if getKybAttemptStatus persisted the case as Approved/Rejected first (brla.controller.ts:891-900), but that path does not enqueue an email. If the webhook was missed and the client polls first, the reconciliation worker can never recover the notification. Enqueue before that terminal write, or keep these cases eligible while separately preventing pre-deployment backfill mail.
  apps/api/src/api/workers/kyb-status.worker.ts:60
• “Oldest writes first” does not make this batch drain: pending attempts are neither updated nor removed, so the same first 250 can be selected every hour for up to 60 days. During a webhook outage, later settled attempts can therefore be starved indefinitely. Use a stable keyset cursor (with wraparound), like AlfredpayStatusWorker, rather than repeatedly taking the same prefix.
  apps/api/src/api/services/email/ramp-completion.ts:90
• This recovery query is unbounded. After a prolonged queue/database outage, it loads every missing completion and then performs a quote lookup plus locale lookup for each one sequentially, so a single hourly cycle can become arbitrarily large. Keep the no-age-cutoff guarantee, but process a stable bounded batch per cycle.

  const completed = await RampState.findAll({

docs/architecture-email-notifications.md:8

• This relative link resolves outside docs/ to /security-spec/..., so the architecture document’s security-spec link is broken.
  docs/security-spec/05-integrations/resend.md:97
• These audit checks reference identifiers that do not exist in this change: the function is enqueueRampCompletedEmail, and the migration is 062. As written, reviewers following the normative checklist will search the wrong symbols.
  docs/architecture-email-notifications.md:435
• The table is created by migration 062, not 055 (the same document correctly names 062 in §4). This file map currently points readers to the wrong migration.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 73 changed files in this pull request and generated no new comments.

Suppressed comments (4)

packages/shared/src/services/brla/brlaApiService.ts:414

• sendRequest only casts provider JSON (and even returns undefined when parsing fails), so this production wrapper does not use the newly added aveniaWebhooksListSchema. A malformed or partial Avenia response can therefore make the registration script miss an existing subscription, attempt a duplicate registration, or fail with an unrelated property error. Parse the response with the schema here and fail closed before exposing it.
  packages/shared/src/services/brla/brlaApiService.ts:449
• This assertion does not validate the public-key response at runtime. If Avenia or an intermediary returns a truthy non-string publicKey, it is cached and every genuine webhook fails signature verification until refresh. Check that the field is a non-empty string before returning it.
  apps/api/src/api/services/email/notification.service.ts:231
• The stale-row read and the subsequent abandonment update are not one atomic claim. Because both flow-variant backends run this worker, they can both read the same exhausted sending row and each emit a Slack abandonment alert even though only one transition occurred. Claim/transition stale rows transactionally (for example with a row lock plus SKIP LOCKED or UPDATE ... RETURNING) and alert only for rows claimed by that transaction.

  const exhausted = await EmailNotification.findAll({
    where: { ...staleClaim, attempts: { [Op.gte]: MAX_ATTEMPTS } }
  });

apps/api/src/database/migrations/062-create-email-notifications-table.ts:6

• The PR deployment notes identify this as migration 055-create-email-notifications-table.ts, but the actual migration is numbered 062 and the in-repository docs also reference 062. Update the PR description so deployers and reviewers do not look for or gate deployment on a nonexistent migration 055.