REFRACT Notification

REFRACT Notification is the shared notification layer for the REFRACT Platform. It routes email and SMS notifications for REFRACT Delivery and REFRACT Workflow through either REFRACT Shared Services ACS or your own Azure Communication Services instance.

REFRACT Notification is the cross-cutting notification infrastructure that powers outbound communications for REFRACT Delivery recipient invitations and REFRACT Workflow participant and approver notifications. It is not a standalone product - it is the shared layer underneath those flows.

REFRACT eSign signer emails follow a different path. Because the signing experience is hosted by REFRACT, eSign signer emails originate from the REFRACT eSign Portal rather than from your Processor's notification queue - see REFRACT eSign signer emails below.

Scope

The EMAIL_PROVIDER environment variable controls every notification email that leaves your Dispatcher or Processor - this covers REFRACT Delivery and REFRACT Workflow in full. It does not control REFRACT eSign signer emails, which are sent by the REFRACT eSign Portal.

Two Modes

Two notification routing modes are supported. The mode is set via the EMAIL_PROVIDER environment variable on both your Dispatcher and Processor Function Apps.

`vault-shared` (Default)

The Dispatcher queues notification messages to your Azure Service Bus. Your Processor picks them up and relays each message to the REFRACT Notification service (HMAC-signed, metadata only). REFRACT Shared Services' Azure Communication Services instance handles the actual email delivery.

Customer Azure Subscription                          REFRACT Shared Services
──────────────────────────────────────   ────────────────────────────────────
Dispatcher
  └─ enqueue (metadata-only message)
       └─ [Customer Service Bus]
             └─ Processor NotificationWorker
                  └─ POST /api/notifications/send
                       (HMAC-SHA256 signed, metadata only:
                        recipient email, portal link, notification type)
                                                    └─ REFRACT Notification service
                                                          └─ ACS (email / SMS)

The HMAC-signed POST carries only: recipient email, portal link, notification type, and document name. Document content, file bytes, signatures, and form field data are never included.

`customer-acs`

Your Processor sends REFRACT Delivery and REFRACT Workflow notification emails directly through your own Azure Communication Services instance. For these features, the REFRACT Notification service is never called and no notification metadata transits REFRACT Shared Services.

Customer Azure Subscription
──────────────────────────────────────
Dispatcher
  └─ enqueue (metadata-only message)
       └─ [Customer Service Bus]
             └─ Processor NotificationWorker
                  └─ sendViaCustomerAcs()
                       └─ Your own ACS
                            (ACS_EMAIL_ENDPOINT + ACS_EMAIL_KEY)

customer-acs scope: REFRACT Delivery and REFRACT Workflow fully. REFRACT eSign is not covered.

Setting EMAIL_PROVIDER=customer-acs on both your Dispatcher and Processor routes all notification queue emails through your own ACS - this covers REFRACT Delivery invitations and OTP codes, and REFRACT Workflow participant, approver, and change-request notifications. For these features, no notification metadata transits REFRACT Shared Services.

REFRACT eSign signer emails are not affected by this setting. Signer invitations (initial and sequential), OTP codes, completion notifications, and documents-ready notifications are all sent by the REFRACT eSign Portal through REFRACT Shared Services, regardless of EMAIL_PROVIDER.

REFRACT eSign signer emails

The REFRACT eSign signing experience is hosted by REFRACT. Signers open a REFRACT-hosted portal to view the document, request an access code, and sign. The emails that support that experience are composed and sent by the portal itself, not by your Processor's notification queue - so they do not pass through EMAIL_PROVIDER routing.

This applies to all four eSign signer email types:

Email	Sent by	Trigger
Signer invitation (initial)	REFRACT eSign Portal	Signing session created
Signer invitation (sequential)	REFRACT eSign Portal	Previous signer completes
OTP access code	REFRACT eSign Portal	Signer requests a code on the portal
Completion notification	REFRACT eSign Portal	Final signer completes
Documents-ready notification	REFRACT eSign Portal	Sealed document is ready

What crosses the boundary for these emails is notification metadata only: recipient email address, signer name, document name, requesting organization, and the signing link. Document content, rendered PDF bytes, signature images, and form field values never leave your Azure subscription - the portal holds a link, not the document.

Requester notifications are separate

The table above covers signer-facing emails only. REFRACT eSign can also notify the person who requested the document (per-signer notices, documents-ready, decline, revoke, and seal-failure), but only when requestedByEmail is set on templateSettings.esign. See Requester Notifications for the full breakdown and why generatedBy does not substitute for it.

If strict zero-transit is required

If your requirements prohibit any notification metadata transiting REFRACT Shared Services, customer-acs provides that for REFRACT Delivery and REFRACT Workflow. It does not currently provide it for REFRACT eSign. Contact us to discuss your requirements.

Environment Variable Reference

Setting	`vault-shared` (default)	`customer-acs`
`EMAIL_PROVIDER`	`vault-shared` or blank	`customer-acs`
`VAULT_NOTIFICATION_API_URL`	required	not needed
`VAULTNOTIF_SIGNING_KEY`	required	not needed
`ACS_EMAIL_ENDPOINT`	blank	customer's ACS URL
`ACS_EMAIL_KEY`	blank	customer's ACS key

Required variables for customer-acs mode:

Variable	Set on	Description
`EMAIL_PROVIDER`	Dispatcher + Processor	Set to `customer-acs` on both Function Apps
`ACS_EMAIL_ENDPOINT`	Dispatcher + Processor	Your ACS endpoint URL
`ACS_EMAIL_KEY`	Dispatcher + Processor	Your ACS access key
`ACS_EMAIL_FROM`	Dispatcher + Processor	Verified sender address (e.g. `noreply@contoso.com`)

Choosing a Mode

	`vault-shared`	`customer-acs`
Setup required	None (default)	ACS resource in your tenant; set on both Function Apps
REFRACT Shared Services in notification path	Yes (metadata only - email address, portal link, notification type)	No, for REFRACT Delivery and REFRACT Workflow. Yes for REFRACT eSign signer emails.
Document data crosses boundary	Never	Never
Applies to	REFRACT Delivery, REFRACT Workflow	REFRACT Delivery, REFRACT Workflow
Use when	Standard deployments	Zero-transit requirements for REFRACT Delivery and REFRACT Workflow notification metadata

What Each Product Sends

Product	Notification	Routed via `EMAIL_PROVIDER`
REFRACT Delivery	Recipient delivery invitation	Yes
REFRACT Delivery	OTP code (when `requireOtp: true`)	Yes
REFRACT Workflow	Participant portal link	Yes
REFRACT Workflow	Approver notification	Yes
REFRACT Workflow	Change-request and resubmission notifications	Yes
REFRACT eSign	Signer invitation (initial + sequential)	No - sent by the REFRACT eSign Portal
REFRACT eSign	OTP access code	No - sent by the REFRACT eSign Portal
REFRACT eSign	Completion notification	No - sent by the REFRACT eSign Portal
REFRACT eSign	Documents-ready notification	No - sent by the REFRACT eSign Portal

Data Sovereignty

In both modes, and for every product including REFRACT eSign, document content, rendered PDF bytes, form field values, signature images, and file attachments are never included in any notification message. Notifications carry only the minimum metadata required to perform delivery: recipient email, portal access link, notification type, and document name.