Orion — Event-Driven Notification System

01Purpose & Scope

Orion currently sends no outbound notifications. Job assignments go unannounced, invoice creation is silent, and technicians learn of new work only by checking the portal manually. This document specifies an event-driven notification system for the Orion field service portal whose primary channel is transactional email, built without any polling — every notification is triggered by a GCP Pub/Sub event pushed from the Orion BFF to a dedicated microservice.

02Current State

Orion has no outbound notification capability. The table below documents the current situation for each domain within the portal.

03Event Architecture

All Orion notification triggers flow through GCP Pub/Sub using push subscriptions. The Orion BFF publishes a lightweight JSON envelope and returns immediately — no knowledge of notification logic, no polling, no callbacks. Pub/Sub delivers the message to the notification service endpoint over HTTPS.

3.1 — Topic taxonomy

Three topics are in scope for this document — all published exclusively by the Orion BFF. Topics are created once in the metiss-dev GCP project and can gain additional subscribers later without changes to Orion or the notification service.

3.2 — Event envelope schema

All events share the same envelope. Source-specific data goes in payload. The notification service acts on the envelope fields; it never assumes payload structure beyond what is documented in the event catalog (Section 07).

{
  "event_id":   "evt_01J3KQZ...",   // ULID — used as idempotency key
  "event_type": "job.assigned",      // dot-namespaced string
  "source":     "orion-bff",         // publishing service slug
  "created_at": "2026-07-10T14:23:00Z",
  "payload": {
    "job_id":    "uuid-...",         // resource ID — no PII in envelope
    "actor_id":  "uuid-...",         // user who triggered the event
    "recipient_ids": ["uuid-..."]    // user IDs who should be notified
  }
}

3.3 — Why push, not pull

Pub/Sub supports two subscription modes. This design uses push exclusively.

04Notification Service

A new notification-service FastAPI microservice is introduced. It has a single responsibility: receive Pub/Sub push messages, decide who to notify and how, render the appropriate email template, and dispatch via Resend. It shares the existing Cloud SQL instance and deploys to Cloud Run alongside the other Metiss microservices.

4.1 — API surface

4.2 — Request lifecycle (push endpoint)

05Email Delivery

5.1 — Email provider: Resend

Resend is selected as the transactional email provider for the following reasons:

5.2 — Template system

Email templates are Jinja2 files stored in notification-service/templates/. Each event type has two template files: an HTML file and a plain-text fallback. Template names follow the pattern {event_type}.html and {event_type}.txt (dots replaced by underscores in filenames).

templates/
  job_assigned.html          job_assigned.txt
  job_status_changed.html    job_status_changed.txt
  job_completed.html         job_completed.txt
  job_cancelled.html         job_cancelled.txt
  invoice_created.html       invoice_created.txt
  invoice_sent.html          invoice_sent.txt
  invoice_paid.html          invoice_paid.txt
  auth_invite_sent.html      auth_invite_sent.txt
  auth_password_reset.html   auth_password_reset.txt
  auth_account_locked.html   auth_account_locked.txt

5.3 — Unsubscribe

Every notification email includes an RFC 8058 List-Unsubscribeheader and a visible “Unsubscribe” link in the footer. The link target is:

GET /unsubscribe
  ?user_id=<uuid>
  &event_type=<type>
  &nonce=<ulid>
  &sig=<hmac-sha256-hex>

The HMAC is computed server-side at send time using a secret key. Verification on click confirms the link was issued by the service and has not been tampered with. No user session is required — a single click opts the user out without a login wall.

06Data Model

Three tables are added to the shared Cloud SQL instance (same database as Orion). No new database or Cloud SQL instance is required.

notification_log

Immutable append-only record of every notification attempt. The idempotency_key column is indexed and used to deduplicate Pub/Sub redeliveries.

user_notification_preference

Per-user, per-event-type opt-in/out. Default is opted in; a row is only written when a user changes a preference from the default.

UNIQUE (user_id, event_type)

notification_template (v2 placeholder)

Reserved for a future DB-managed template system. Not populated or queried in v1 — the service uses filesystem Jinja2 templates. Schema is created now to avoid a migration later.

07Event Catalog

All events in scope for v1 — published exclusively by the Orion BFF. Events marked planned require Orion to add the Pub/Sub publish call before they go live.

08Delivery Guarantees

8.1 — Idempotency

Pub/Sub guarantees at-least-once delivery, not exactly-once. The notification service implements its own exactly-once guarantee at the application layer:

1. Each Pub/Sub message carries a unique messageId generated by GCP. This is stored as idempotency_key in notification_log.
2. Before sending, the service queries notification_log by idempotency_key. If a row exists, the endpoint returns HTTP 200 immediately.
3. The notification_log insert and the Resend API call are not in the same database transaction — Resend has no transactional rollback. Instead, the log row is written after a successful Resend response, keeping the window of unlogged delivery narrow (see failure path below).

8.2 — Retry and backoff

8.3 — Dead-letter topic

The push subscription is configured with a dead-letter topic: platform.notifications.dlq. After 7 delivery attempts (Pub/Sub default), unacknowledged messages are forwarded there. An alert fires on any DLQ message via Cloud Monitoring. DLQ messages are inspected manually and replayed if the root cause is fixed.

09Security

9.1 — Push endpoint authentication

The POST /events/push endpoint is not exposed via the GCP API Gateway (which handles partner/public traffic). It is deployed as a private Cloud Run service accessible only by the Pub/Sub service account. The OIDC token check provides a second layer of verification.

# Pub/Sub push subscription configuration
audience: https://notification-service-<hash>-uc.a.run.app
service_account: pubsub-push-sa@metiss-dev.iam.gserviceaccount.com

9.2 — Resend webhook authentication

Resend signs webhooks using Svix. The POST /events/webhook endpoint verifies the svix-id, svix-timestamp, and svix-signature headers using the Resend webhook signing secret stored in Secret Manager. Requests failing verification are rejected with HTTP 403.

9.3 — Unsubscribe token security

Unsubscribe links are HMAC-SHA256 signed. The service computes:

sig = HMAC-SHA256(
  key  = UNSUBSCRIBE_SECRET,      # from Secret Manager
  data = f"{user_id}:{event_type}:{nonce}"
)

On click, the service recomputes and compares in constant time using hmac.compare_digest. Nonces are ULIDs; a nonce is marked used in user_notification_preference on first verification to prevent replay.

9.4 — PII handling

10Test Plan

11Open Questions