Unity Notifications Service - Event Catalog

🏠 Home › Unity.Notifications / docs

Unity Notifications Service - Event Catalog

Overview

Unity Notifications uses RabbitMQ via MassTransit 7.3.1 for asynchronous messaging. Three dedicated subscriber services consume notification requests and deliver them through AWS channels (SES, Pinpoint, SNS). The API also publishes events for inbound SMS, delivery receipts, and email bounces.

Message Bus Architecture

Bus Queue/Endpoint Service
Email Unity_Notifications_Emails EmailMessaging subscriber
SMS unity.notifications.messaging.consumers.smsmessaging SmsMessaging subscriber
Push Unity_Notifications_PushMessages PushMessaging subscriber

Delivery Mechanism

Component Purpose Configuration
MassTransit 7.3.1 Consumer/publisher framework RabbitMQ transport
RabbitMQ Message broker Host, username, password from environment
BusProxy Outbound event publishing TELS.BusProxy.Client 2.1.5 with S3 fallback

Consumed Events (Inbound)

OutboundEmailEnvelope

Property Value
Source Any TELS service (Tasks, etc.) via BusProxy or direct RabbitMQ
Queue Unity_Notifications_Emails
Consumer EmailMessaging → EmailsEventHandler.ProcessEmail()
Trigger Service needs to send an email
Action Decrypts (if needed), validates, sends via AWS SES, records in DynamoDB

Schema:

{
  "applicationCode": "TASKS",
  "signature": "hmac-signature",
  "encryptedOutboundEmailMessageBase64": "base64-content",
  "createdTimestamp": "2026-03-11T12:00:00Z",
  "messageTags": {"key": "value"}
}

Processing Flow: 1. Message consumed from RabbitMQ 2. Envelope validated (signature check per applicationCode) 3. Content decrypted if encrypted (RSA) 4. Email assembled with attachments (fetched from S3) 5. Sent via AWS SES (or MailKit locally) 6. Audit record written to DynamoDB

OutboundSMS

Property Value
Source Any TELS service via RabbitMQ
Queue unity.notifications.messaging.consumers.smsmessaging
Consumer SmsMessaging → SmsMessagesEventHandler.ProcessSms()
Trigger Service needs to send an SMS
Action Validates phone number, checks opt-in status, sends via AWS Pinpoint, records in SQL Server

Schema:

{
  "dsMessageID": "guid",
  "senderID": "TELS",
  "number": "+15551234567",
  "message": "Your work order is scheduled.",
  "requestorName": "TELS Tasks",
  "optInAction": "None"
}

Processing Flow: 1. Message consumed from RabbitMQ 2. Phone number validated (E.164 format via libphonenumber) 3. Blacklist/restriction check 4. Opt-in preference checked 5. Sent via AWS Pinpoint 6. Message recorded in SQL Server (SmsMessages + SmsMessageParts)

Error Handling: - Polly retry policy for transient failures

MobilePushNotification

Property Value
Source Any TELS service via RabbitMQ
Queue Unity_Notifications_PushMessages
Consumer PushMessaging → PushNotificationsEventHandler.ProcessNotification()
Trigger Service needs to send a push notification
Action Sends via AWS SNS to target application/device

Schema:

{
  "application": "TELS Mobile",
  "recipient": "device-endpoint-arn",
  "message": "New task assigned",
  "extraInformation": {"taskId": "12345"},
  "badge": 3
}

Published Events (Outbound)

InboundSMS

Property Value
Source API (PinpointController or HomeController)
Trigger SMS received via Pinpoint SNS webhook or Vonage webhook
Delivery BusProxy (S3 fallback)
Known Consumers Downstream services interested in SMS responses

Schema:

{
  "recipientID": "TELS",
  "number": "+15551234567",
  "message": "OK",
  "dsMessageID": "guid",
  "timestamp": "2026-03-11T12:00:00Z",
  "concat": false,
  "concatReference": null,
  "concatTotal": null,
  "concatPart": null,
  "previousMessageDSMessageID": null
}

DeliveryReceiptSMS

Property Value
Source API (PinpointController or HomeController)
Trigger Delivery receipt received from Pinpoint Firehose or Vonage
Delivery BusProxy (S3 fallback)
Known Consumers Downstream services tracking SMS delivery

Schema:

{
  "directSupplySenderID": "TELS",
  "dsMessageID": "guid",
  "updatedWhenUtc": "2026-03-11T12:05:00Z",
  "deliveryStateID": 1,
  "message": "Delivered"
}

Delivery States: 0=Unknown, 1=Success, 2=Failed

OutboundEmailBounced

Property Value
Source API (EmailController.HandleBounce)
Trigger AWS SES bounce notification received via SNS
Delivery MassTransit (direct RabbitMQ)
Known Consumers Services that need to handle email bounces

Schema:

{
  "bouncedEmailToAddresses": ["bad@example.com"],
  "subject": "Original subject",
  "messageTags": {"correlationId": "12345"}
}

Message Flow Diagrams

Outbound Email Flow

Upstream Service (e.g., Tasks)
  → Publishes OutboundEmailEnvelope via BusProxy/RabbitMQ
  → Queue: Unity_Notifications_Emails
  → Consumer: EmailMessaging
  → Decrypts (if encrypted)
  → Fetches attachments from S3
  → Sends via AWS SES
  → Records audit in DynamoDB
  → (Later) SES sends bounce to SNS
  → SNS calls /Email/HandleBounce
  → API publishes OutboundEmailBounced

SMS Send/Receive Flow

Outbound:
  Upstream Service
    → Publishes OutboundSMS via RabbitMQ
    → Queue: unity.notifications.messaging.consumers.smsmessaging
    → Consumer: SmsMessaging
    → Validates phone, checks opt-in
    → Sends via AWS Pinpoint
    → Records in SQL Server
    → Pinpoint sends delivery receipt
    → Firehose calls /Pinpoint/DeliveryReceipt
    → API publishes DeliveryReceiptSMS

Inbound:
  User sends SMS reply
    → AWS Pinpoint → SNS → /Pinpoint/Inbound
    → API publishes InboundSMS via BusProxy
    → Records in SQL Server

Push Notification Flow

Upstream Service
  → Publishes MobilePushNotification via RabbitMQ
  → Queue: Unity_Notifications_PushMessages
  → Consumer: PushMessaging
  → Sends via AWS SNS to device endpoint

Message Queue Configuration

RabbitMQ Connection

Setting Source Description
Host RABBITMQ__MQHOST RabbitMQ broker hostname
Username RABBITMQ__USERNAME Authentication
Password RABBITMQ__PASSWORD Authentication

Contract Package

Package Version Messages Provided
Unity.Notifications.Messaging v1.12.0 OutboundEmailEnvelope, OutboundEmailMessage, OutboundSMS, InboundSMS, DeliveryReceiptSMS, MobilePushNotification, OutboundEmailBounced

Key Files

File Purpose
Unity.Notifications.Web/Startup.cs API configuration, MassTransit setup
Unity.Notifications.Web/Controllers/ 4 controllers (Email, Home, Pinpoint, Diagnostics)
Unity.Notifications.Messaging.Consumers/Email/ Email consumer + AWS SES sender
Unity.Notifications.Messaging.Consumers/Sms/ SMS consumer + AWS Pinpoint sender
Unity.Notifications.Messaging.Consumers/Push/ Push consumer + AWS SNS sender
Unity.Notifications.Messaging/ Shared message contracts

Summary