Notification Service API

Centralized notification delivery service for email, SMS, HubSpot, and Slack channels.

Overview

The Notification Service is a centralized API for all patient and internal notifications. Instead of each service integrating directly with SES, Twilio, HubSpot, and Slack, callers send a single POST /notify/send request and let the service handle template resolution, channel routing, delivery, and logging.

Base URL

https://api.yourera.com/notify

How It Works

1. Caller sends a POST /notify/send with a notification type and recipient data
2. Service resolves the template for that notification type
3. Template engine renders the template with provided variables
4. Channel config determines which channels are enabled for this type
5. Service dispatches to all enabled channels (email, SMS, HubSpot, Slack)
6. Each channel delivery is independent — one failure doesn't block others
7. All delivery attempts are logged with status, channel, and timestamps

Authentication

The /notify/send endpoint requires HMAC-SHA256 authentication. Admin endpoints (/notify/templates/*, /notify/channels/*) require an Admin JWT token.

HMAC Authentication (Send Endpoint)

Signature Formula

HMAC-SHA256(apiSecret, timestamp + '.' + JSON.stringify(body))

Node.js Example

import crypto from 'node:crypto';

const timestamp = new Date().toISOString();
const body = JSON.stringify({
  type: 'prescription_approved',
  recipient: { email: 'patient@example.com', phone: '5551234567' },
  variables: { patientName: 'Jane Doe', medication: 'Semaglutide' }
});

const signature = crypto
  .createHmac('sha256', API_SECRET)
  .update(timestamp + '.' + body)
  .digest('hex');

await fetch('https://api.yourera.com/notify/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: body,
});

Send Notification

Request Body

Example Request

{
  "type": "prescription_approved",
  "recipient": {
    "email": "jane@example.com",
    "phone": "5041234567",
    "name": "Jane Doe"
  },
  "variables": {
    "patientName": "Jane Doe",
    "medication": "Semaglutide 5mg/mL",
    "pharmacyName": "Galleria Medical Pharmacy"
  }
}

Success Response 200

{
  "success": true,
  "channels": [
    { "channel": "email", "status": "sent" },
    { "channel": "sms", "status": "sent" }
  ],
  "logId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Notification Types

43 notification types organized in 3 categories. Each type is seeded on first deployment with an email template. SMS templates are added as A2P 10DLC registration completes.

General (29 types)

Orders (12 types)

Shipping (6 types)

Channel Matrix

The full channel matrix for all 43 notification types is managed through the Admin Portal. On initial deployment, all types are seeded with Email enabled and all other channels disabled. Channels can be toggled per-type via the admin UI or the PUT /notify/channels/:type API.

Available Channels

Template Engine

Templates use Mustache-style {{variableName}} placeholders. The template engine substitutes variables and handles edge cases gracefully:

• Missing variables render as empty string (no crash)
• undefined / null variables render as empty string
• Variables in email templates are HTML-escaped (XSS prevention)
• Variables in SMS templates are rendered raw (plain text)
• Empty template body causes that channel to be skipped

Example

// Template
"Hi {{patientName}}, your {{medication}} has been approved!"

// Variables
{ "patientName": "Jane", "medication": "Semaglutide" }

// Result
"Hi Jane, your Semaglutide has been approved!"

Templates CRUD

Admin endpoints for managing notification templates. Requires Admin JWT in Authorization: Bearer <token>.

Update Request Body

Channels CRUD

Admin endpoints for managing channel configuration per notification type.

Update Request Body

{
  "email": true,
  "sms": true,
  "hubspot": false,
  "slack": false
}

Delivery Log

Every notification dispatch is logged with:

Health Check

{
  "status": "ok",
  "service": "notification-service",
  "timestamp": "2026-03-20T12:00:00.000Z"
}

Admin Portal Integration

The admin portal at admin.yourera.com will include a Notifications page for managing the full notification lifecycle. The page provides:

• Type listing — all 43 types grouped by category (General, Orders, Shipping)
• Channel toggles — enable/disable email, SMS, push per type
• Template editor — edit email subject, HTML body, text body, SMS body for each type
• Delivery log viewer — search/filter notification delivery history
• Test send — send a test notification to verify templates

The admin portal calls the notification service Admin JWT-authenticated endpoints:

Roadmap

Phase 1 — Email Only (Current)

• 43 notification types seeded with email templates
• Email delivery via AWS SES (noreply@yourera.com)
• Admin portal can toggle types on/off and edit templates
• SMS channel disabled (pending Twilio A2P 10DLC registration)

Phase 2 — SMS

• Complete Twilio A2P 10DLC registration
• Enable SMS templates for patient-facing notifications
• Admin portal gains SMS template editing

Phase 3 — Intake Magic Link + Abandoned Checkout

• magic_link and abandoned_checkout types go live
• Intake gateway tracks session start timestamps
• 30-minute inactivity trigger sends abandoned_checkout email
• Magic link includes signed token for intake resume

Phase 4 — Scheduled Notifications

• Follow-up reminders (due, past due, 2 days)
• Check-in reminders (3-month, 4-month)
• Subscription renewal notices
• Delivery estimates (tomorrow, out for delivery)
• Requires a notification scheduler (cron or EventBridge)

Phase 5 — Push Notifications

• Mobile push via APNs/FCM
• In-app notification center
• Admin portal gains push template editing

What's Missing (Dependency Tracker)