Skip to main content

Notification Config

Creating or updating a notification for NSS starts with the notification config. The config is a yaml file that will define everything needed to send a notification.

A sample config can be found at notification_configs/sample.yml.

All configs live in the notification_configs directory within the notifications repository

Naming​

The config file should be name of the notification with words separated by an underscore. The .yml file extension should be used.

Example:

profile_insights_views.yml

Versioning​

Notification configs are versioned to allow for changes over time while maintaining backward compatibility. The version is specified in the notification_version field and typically matches the directory structure (e.g., v1, v2).

When creating a new version of a notification:

  • Create a new config file in the appropriate version directory
  • Update the notification_version field to match the new version
  • Ensure the notification_name remains consistent across versions (unless creating a new notification entirely)

Configuration Options​

All fields are optional unless otherwise noted; required fields are marked with "required". Fields with default values are marked with "default:". Fields with a set of allowed values are marked with "allowed values:".

Top-Level Fields​

notification_name (string, required)​

Name of the notification as identified in the file structure. This is a unique string that identifies the notification and should match the filename (without the .yml extension).

Example:

notification_name: profile_insights_views

notification_version (string, required)​

Version of the notification as identified in the file structure. This typically matches the version directory (e.g., v1, v2).

Example:

notification_version: v2

notification_preference_name (string)​

Key of the preference used to check a user's preference for receiving this notification. This is required unless skip_preference_check is set totrue. The string should be separated by underscores.

Example:

notification_preference_name: profile_views

platform (string, allowed values: hai, recruiting, default: recruiting)​

Platform name that the notification is associated with.

Example:

platform: recruiting

priority (string, allowed values: low, default, default: default)​

Priority level of the notification. Low priority notifications may take longer to deliver. Use low for non-urgent/high-volume notifications such as digests.

Example:

priority: low

skip_preference_check (bool, default: false)​

Determines whether the notification checks notification_preference_name for a user prior to send. When set to true, the notification will be sent regardless of user preference settings. This is commonly used for critical notifications like Terms of Service updates.

Example:

skip_preference_check: true

user_types ([]string, allowed values: career_services, employers, students)​

List of user types that can receive the notification. If not specified, the notification may be sent to all user types (depending on other configuration).

Example:

user_types:
  - students

required_attributes ([]string)​

List of properties that must be passed in the body of the request. These attributes are validated to be present before the notification is sent.

Example:

required_attributes:
  - view_count
  - lookback_period

primary_entity_attribute (string)​

The attribute used to identify the primary object of the notification. This is used for entity tracking and analytics.

Example:

primary_entity_attribute: job_posting_id

primary_entity_urn_nid (string)​

Primary entity URN namespace identifier.

primary_entity_urn_nss_attribute (string)​

Primary entity URN namespace-specific string attribute.

analytics_metadata (object)​

Metadata for analytics tracking. This information is included in event tracking across notification channels.

analytics_metadata.product_bucket (string, required)​

Product bucket for the notification. This field is included in event tracking across all channels and is used to categorize notifications for analytics purposes.

Example:

analytics_metadata:
  product_bucket: profile_insights

analytics_metadata.item_type (string)​

Type of item for the notification. This field is included in Segment in-app event tracking.

Example:

analytics_metadata:
  product_bucket: profile_insights
  item_type: profile_view

analytics_metadata.item_id (string)​

ID of the item for the notification. This field is included in Segment in-app event tracking.

Example:

analytics_metadata:
  product_bucket: profile_insights
  item_type: profile_view
  item_id: "12345"

channels (object)​

Channels to send the notification through. Excluded channels are considered not enabled. Allowed channel values: email, in-app, push.

Each channel can be independently enabled or disabled. At least one channel must be enabled for the notification to be sendable.

Email Channel​

channels.email.enabled (bool, required)​

Turns on/off the creation of email notifications.

Example:

channels:
  email:
    enabled: true
channels.email.sending_platform (string, required if email enabled, allowed values: mailgun, iterable)​

Vendor used to send the email. Choose mailgun for standard transactional emails or iterable for marketing campaigns.

Example:

channels:
  email:
    enabled: true
    sending_platform: mailgun
channels.email.sending_domain_name (string)​

Domain reference name used to send the email. This maps to actual email domains configured in the system.

Possible values:

  • ai_domain
  • notification_domain
  • core_notification_domain
  • campaign_email_domain
  • mass_mail_domain

For example, campaign_email_domain maps to g.joinhandshake.com in US Production.

Example:

channels:
  email:
    enabled: true
    sending_platform: mailgun
    sending_domain_name: campaign_email_domain
channels.email.mailer.name (string, required if sending_platform is mailgun)​

Rails ActionMailer class name that handles the email template and delivery.

Example:

channels:
  email:
    enabled: true
    sending_platform: mailgun
    mailer:
      name: NotificationsMailer
channels.email.mailer.method (string)​

Method in the mailer class used to deliver the email. If not specified, a default method may be used based on the notification name.

Example:

channels:
  email:
    enabled: true
    sending_platform: mailgun
    mailer:
      name: NotificationsMailer
      method: profile_insights_views

In-App Channel​

channels.in-app.enabled (bool, required)​

Turns on/off the creation of in-app notifications.

Example:

channels:
  in-app:
    enabled: true
channels.in-app.platform_exclusions ([]object)​

List of platforms and versions that this in-app notification should be excluded from. This allows you to target specific platform versions.

Example:

channels:
  in-app:
    enabled: true
    platform_exclusions:
      - platform: android
        version: "*"
      - platform: web
        version: "*"
channels.in-app.platform_exclusions[].platform (string, required, allowed values: web, ios, android)​

Platform name to exclude from receiving the notification.

Note: Web does not have versions; if platform: "web", then version: "*" is the only valid value.

Example:

platform_exclusions:
  - platform: web
    version: "*"
channels.in-app.platform_exclusions[].version (string, required)​

Semver versions to exclude (use * for all versions). Note this is an exclusion, so <=1.2.3 will exclude version 1.2.3 and below.

Examples:

# Exclude all versions
- platform: android
  version: "*"

# Exclude versions 1.2.3 and below
- platform: ios
  version: "<=1.2.3"

# Exclude versions above 2.0.0
- platform: ios
  version: ">2.0.0"

Push Channel​

channels.push.enabled (bool, required)​

Turns on/off the creation of push notifications.

Example:

channels:
  push:
    enabled: true
channels.push.sending_platform (string, required if push enabled, allowed values: firebase)​

Vendor used to send the push notification. Currently, only firebase is supported.

Example:

channels:
  push:
    enabled: true
    sending_platform: firebase
channels.push.platform_exclusions ([]object)​

List of platforms and versions that this push notification should be excluded from. Push notifications are only available for iOS and Android (not web).

Example:

channels:
  push:
    enabled: true
    sending_platform: firebase
    platform_exclusions:
      - platform: android
        version: "<=5.0.0"
channels.push.platform_exclusions[].platform (string, required, allowed values: ios, android)​

Platform name to exclude from receiving the push notification.

Example:

platform_exclusions:
  - platform: android
    version: "*"
channels.push.platform_exclusions[].version (string, required)​

Semver versions to exclude (use * for all versions). Note this is an exclusion, so <=1.2.3 will exclude version 1.2.3 and below.

Examples:

# Exclude all Android versions
- platform: android
  version: "*"

# Exclude iOS versions 6.1.0 and below
- platform: ios
  version: "<=6.1.0"

Example Configurations​

Minimal In-App Notification​

The simplest configuration required to send an in-app notification:

notification_name: tos_update
notification_version: v1
skip_preference_check: true
channels:
  in-app:
    enabled: true

Multi-Channel Notification​

A notification that sends via email, in-app, and push:

notification_name: profile_insights_views
notification_version: v2
notification_preference_name: profile_views
platform: recruiting
user_types:
  - students
required_attributes:
  - view_count
  - lookback_period
analytics_metadata:
  product_bucket: profile_insights
  item_type: profile_view
channels:
  email:
    enabled: true
    sending_platform: mailgun
    mailer:
      name: NotificationsMailer
      method: profile_insights_views
  in-app:
    enabled: true
    platform_exclusions:
      - platform: web
        version: "*"
      - platform: android
        version: "*"
  push:
    enabled: true
    sending_platform: firebase
    platform_exclusions:
      - platform: android
        version: "*"

Email-Only Notification​

A notification that only sends via email:

notification_name: network_digest
notification_version: v1
notification_preference_name: network_digest
user_types:
  - students
analytics_metadata:
  product_bucket: network
channels:
  email:
    enabled: true
    sending_platform: mailgun
    sending_domain_name: campaign_email_domain
    mailer:
      name: NotificationsMailer
      method: network_digest
  in-app:
    enabled: false
  push:
    enabled: false

Validation​

Notification configs are validated automatically in CI to prevent malformed configurations from reaching production. The validation ruleset runs against every notification config in the Notifications repo.

Running Validation Locally​

You can run the validation checks locally with:

go run notification_configs_test/ruleset/main.go

Validation Rules​

The current rule set can be found in notification_configs_test/ruleset/rules/rule.go.

For more information on adding custom validation rules, see Add a Notification Config Rule.