# Notifications configuration

Use this page to understand notification service and email notification fields for Ripple Custody. The example shows one possible configuration shape; SMTP provider, credentials, resource values, scaling, and delivery policy depend on your deployment.

This page applies to on-premise deployments only. For current defaults and the full supported schema, use the configuration packaged with your release.

## What this config controls

The notification system handles notification processing, persistence, real-time delivery, and optional email delivery. Email notification settings are configured under `harmonize.notifications.email`. The notification service component is configured under `components.notification`.

## Email fields

Location: `harmonize.notifications.email`

| Parameter | Type | Default | Description |
|  --- | --- | --- | --- |
| `enabled` | boolean | `false` | Enables email notifications. |
| `sender` | string | `harmonize@example.com` | Sender address for email notifications. |
| `smtp.host` | string | `smtp.example.com` | SMTP server hostname. |
| `smtp.port` | string | `"25"` | SMTP server port. Common values: `25`, `465`, `587`, `2525`. |
| `smtp.username` | string | - | SMTP authentication username. |
| `smtp.password` | string | - | SMTP authentication password. Store through your secret-management process. |


SMTP port notes:

| Port | Protocol |
|  --- | --- |
| `25` | SMTP |
| `465` | SMTPS |
| `587` | SMTP with STARTTLS |
| `2525` | SMTP with STARTTLS |


## Notification component fields

Location: `components.notification`

| Field | Description |
|  --- | --- |
| `enabled` | Enables the notification component. |
| `image.repository` | Notification service image repository. |
| `image.tag` | Notification service image tag. |
| `replicas` | Number of notification service replicas. |
| `resources.requests` | CPU and memory requests. |
| `resources.limits` | CPU and memory limits. |
| `service.main.ports.http.port` | Service HTTP port. |
| `service.main.ports.http.targetPort` | Container target port. |
| `autoscaling` | Horizontal autoscaling settings, where exposed by your release. |
| `verificationCode.compatMode` | Whether the notification service also stores the legacy, formula-based verification code on signing requests so that mobile apps older than version 5.12.0 keep matching the web UI. Default `true`. Set to `false` only after most active devices run app version 5.12.0 or later. See [Verification code compatibility mode](#verification-code-compatibility-mode). |


Resource and replica values are workload-dependent. Set them based on expected notification volume and observed runtime behavior.

## Environment variables

| Variable | Description | Example or source |
|  --- | --- | --- |
| `LOG_LEVEL` | Notification service log level. | `info`, `debug`, `warn`, `error` |
| `POSTGRES_URL` | PostgreSQL connection string. | Secret |
| `VERIFICATION_CODE_COMPAT_MODE` | Controls verification code compatibility mode. Any value other than the string `false` keeps compatibility mode on. Set by the `verificationCode.compatMode` Helm value. | `true` |


OAuth credentials, database schema, and inter-service URLs are managed by the deployment configuration unless explicitly exposed.

## Notification templates

The notification service uses built-in templates for notification categories such as transaction updates, approval requests, security alerts, system notifications, and custom application notifications.

## Constraints and relationships

- Email notifications require SMTP connection details.
- SMTP credentials should be supplied through your secret-management process.
- Notification persistence requires PostgreSQL connectivity.
- Event-driven notification processing depends on AMQP configuration.
- Notification APIs depend on OAuth authentication configuration.
- Run the notification service with a single replica. It keeps signature-polling state in process memory.
- When you upgrade to a release that includes server-issued verification codes, upgrade the notification service before the OAuth server and the web application. Both refuse to show a signing or login code that the notification service didn't issue.
- On startup, the notification service applies its database migrations automatically, including a one-time backfill that writes the legacy verification code onto signing requests created before the upgrade. The backfill isn't reversible. Without it, pending requests would be unsignable from an upgraded phone until they expired.


## Verification code compatibility mode

From the release that ships server-issued verification codes, the notification service generates the two-digit code that users match between the web UI and the **Ripple Custody: Auth & Sign** app. Mobile app versions earlier than 5.12.0 don't support server-issued codes, so the service ships with a compatibility mode that stores a legacy code alongside the server-issued one. While compatibility mode is on, older apps keep matching the web UI.

Turn compatibility mode off only when at least 95 percent of active devices have registered through the secure registration flow for 14 consecutive days. The service logs one line per device registration, `Device registration received.` with `secured: true` or `secured: false`, which gives you the adoption figure. After you turn the mode off, a device that still runs an older app shows a code that doesn't match the web UI and can't sign. If users report that the numbers don't match, turn compatibility mode back on and check that the affected users have updated the app. Turning it back on is a configuration change and a restart, not a redeployment.

## Example

This example shows email notification settings and the notification component in one deployment values file:

```yaml
harmonize:
  notifications:
    email:
      enabled: true
      sender: "noreply@example.com"
      smtp:
        host: "smtp.example.com"
        port: "587"
        username: "<smtp-user>"
        password: "<smtp-password>"

components:
  notification:
    enabled: true
    replicas: 1
    resources:
      limits:
        cpu: 1000m
        memory: 1024Mi
      requests:
        cpu: 100m
        memory: 256Mi
    service:
      main:
        ports:
          http:
            port: 80
            targetPort: 3000
```

## Related topics

- [OAuth server configuration](/pt-br/products/custody/v1.42/deployment/reference/oauth-server)
- [AMQP configuration](/pt-br/products/custody/v1.42/deployment/reference/amqp)
- [Networking configuration](/pt-br/products/custody/v1.42/deployment/reference/networking)
- [PostgreSQL configuration](/pt-br/products/custody/v1.42/deployment/reference/postgresql)