Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Providers

novu-bridge: Providers and Gateways (simplified)

Overview

This page covers how novu-bridge reaches SMS, WhatsApp and email gateways, the DIGIT providers that some of those gateways need inside Novu's worker, and how to add a provider type.

Code location: backend/novu-bridge/ Operators add providers at: Configurator → Notifications → Providers

Details

1. How providers work

  • Every provider an operator adds is a Novu integration. novu-bridge never stores credentials.

  • A workspace with its own Novu organisation keeps its providers there. All rules on this page apply to each organisation alike.

Flow when a provider is added

  1. POST /novu-adapter/v1/providers receives the request.

  2. The bridge validates the credentials against the catalogue.

  3. It copies them into Novu’s credential keys (ProviderCatalog.toNovuCredentials).

  4. It creates the Novu integration.

Flow when a message is sent

  1. The bridge triggers the channel’s Novu workflow: complaints-sms, complaints-whatsapp or complaints-email.

  2. Novu’s worker calls the gateway through the provider class named by the integration’s providerId.

How providers work

Every provider an operator adds is a Novu integration, and novu-bridge never stores credentials. A workspace with its own Novu organisation (tenant-accounts.md) holds its providers there; everything on this page applies to each organisation alike. POST /novu-adapter/v1/providers validates the credentials against the catalogue, copies them into Novu's credential keys (ProviderCatalog.toNovuCredentials) and creates the integration. On dispatch, the bridge triggers the channel's Novu workflow (complaints-sms, complaints-whatsapp or complaints-email). Novu's worker then calls the gateway through the provider class named by the integration's providerId.

Catalogue

  • ProviderCatalog.types() defines six types. All use the novu transport.

  • The catalogue fields are exactly the credential keys of the matching Novu provider.

  • The Configurator builds its credential form from GET /novu-adapter/v1/providers/catalog, so a new type needs no UI change.

Type
Channel
Novu provider
Fields → Novu credential keys
Where the provider class lives

twilio-sms

SMS

twilio

accountSid, token, from

upstream Novu

twilio-whatsapp

WHATSAPP

twilio

accountSid, token, from

upstream Novu

smtp

EMAIL

nodemailer

host, port, user, password, from, senderName, secure

upstream Novu

smscountry

SMS

smscountry

user, password, from, baseUrl (optional)

DIGIT, mounted into the worker

ozeki

SMS

ozeki

baseUrl, user, password, from (optional)

DIGIT, mounted into the worker

jasmin

SMS

jasmin

baseUrl, user, password, from (optional)

DIGIT, mounted into the worker

Integration identifiers

  • Format: <type>-<hash>.

  • typeFromIdentifier maps an identifier back to its type using TYPES_LONGEST_FIRST. Credential rotation uses this.

  • Callers may choose their own identifier, but it must start with <type>-. Otherwise: 400 NB_INVALID_PROVIDER.

  • An unmarked integration derives its type from its Novu provider ID, but only if that ID names exactly one type (deriveType).

2. DIGIT Worker Providers

Why they exist

Novu’s generic SMS provider (generic-sms) always POSTs JSON and expects a JSON reply. Three gateways don’t fit:

Gateway
Problem

SMSCountry

Takes a form-encoded request; replies in plain text

Jasmin

Replies in plain text

Ozeki

Returns HTTP 200 even for rejections, so a failed send would be recorded as sent

How it works

  • Novu’s approach is one provider class per gateway, compiled into the worker.

  • DIGIT adds its own classes to the stock worker image at start-up, with no custom image.

  • Code: backend/novu-bridge/novu-worker-providers/

  • The worker starts with:

    • NODE_OPTIONS=--require /opt/digit-novu-providers/register.js

    • DIGIT_NOVU_PROVIDERS=required

    • the directory mounted read-only at /opt/digit-novu-providers

  • This works because the Novu worker isn’t bundled. register.js patches the same SmsFactory the worker uses.

File
What it is

smscountry.js, jasmin.js, ozeki.js

One gateway each: a provider class extending Novu's own BaseProvider, plus the handler that builds it from the integration's credentials

register.js

The preload. It wraps the worker's SmsFactory.getHandler, so an integration whose providerId is one of these gets DIGIT's handler and every other one goes to Novu's own lookup unchanged. It is also the redaction boundary: every error a send throws leaves it as a plain, redacted Error (see Gateway notes)

novu.js

Resolves Novu's internals (BaseProvider, BaseSmsHandler, SmsFactory, axios) from inside the image

test/, run-tests.sh

Tests, run inside the stock worker image they patch

What changes and what doesn’t

Component
Status

Worker

Patched by register.js

API

Stays stock. Accepts any providerId; these providers use existing keys (user, password, from, baseUrl)

ws

Stays stock

Dashboard

Stays stock. Shows these integrations without a logo or form, which is fine because providers are managed in the Configurator

Failure is loud by design.

The worker refuses to boot (with a [digit-novu-providers] error) if:

  • a provider file fails to load, or

  • the image isn’t a verified Novu version (SUPPORTED_WORKER_VERSIONS in register.js, currently 2.3.0).

On success, it logs: [digit-novu-providers] SMS providers registered in the Novu worker: smscountry, jasmin, ozeki

Which processes register

NODE_OPTIONS reaches every node process in the container, so register.js decides per process:

  • The image entrypoint (apps/worker/dist/main.js) always registers.

  • With DIGIT_NOVU_PROVIDERS=required (set by Compose and Helm), every other process also registers, except the dotenv helper (dist/dotenvcreate.mjs).

  • Without the variable, other processes are skipped with a WARNING: NOT registering ... line on stderr.

Why this matters: a worker without the providers fails quietly:

  1. The Configurator saves an SMSCountry, Ozeki or Jasmin provider.

  2. The trigger is accepted, and the dispatch row reads SENT.

  3. The step then dies in Novu with Sms handler for provider smscountry is not found.

migrate-notifications.py refuses to create such a provider if the running novu-worker doesn’t preload them. Twilio and SMTP don’t depend on the preload.

If your worker runs without the preload

(Helm worker.digitProviders.enabled: false, or a hand-rolled worker.)

Set NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS=false (default true). The bridge then:

  • Hides smscountry, ozeki and jasmin from GET /providers/catalog.

  • Refuses to create, rotate, re-enable or test them: 400 NB_PROVIDER_TYPE_UNAVAILABLE. Renaming, disabling and deleting still work, so old ones can be cleaned up.

  • Records as SKIPPED / NB_PROVIDER_UNAVAILABLE any channel that selects one of them.

  • Does the same for channels with no provider selected if Novu’s default for that channel is one of them. The default is: the integration named by NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP (WhatsApp), else Novu’s primary active integration, else every active one.

    • This only catches integrations created before the flag was turned off, or created directly in Novu.

    • It uses the same cached list (one Novu call per NOVU_BRIDGE_PROVIDER_AVAILABILITY_CACHE_TTL_MS).

    • If the list can’t be read, the bridge delivers anyway, so a blip in Novu doesn’t block legacy traffic.

3. Deployment

Method
How it works

Compose

./deploy.sh copies the directory (without tests) to /opt/digit/novu-worker-providers. NOVU_WORKER_PROVIDERS_DIR in /opt/digit/.env points the volume at it. If the files change, the deploy restarts novu-worker. Running straight from local-setup/ mounts the repo copy. Nothing to set in host_vars.

Helm

The backbone novu chart keeps a copy in files/novu-worker-providers/. A ConfigMap serves it, the worker mounts it, and a checksum annotation rolls pods on change. worker.digitProviders.enabled (default true) switches it off. If off, set NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS=false.

local-setup/tests/static/deployment-contracts.test.ts fails if the chart copy drifts from the source.

4. Upgrade Novu

The providers rely on Novu internals (file paths, SmsFactory.getHandler, the handler interface). Before bumping the worker image:

  1. Run the tests against the new image: NOVU_TEST_IMAGE=ghcr.io/novuhq/novu/worker:<version> backend/novu-bridge/novu-worker-providers/run-tests.sh

  2. Fix any failures, add the version to SUPPORTED_WORKER_VERSIONS in register.js, and copy the runtime files to the chart.

  3. Send one message through each provider against a mock gateway (developer-guide.md).

Skipping step 2 leaves the worker refusing to boot, which is intentional. In an emergency, DIGIT_NOVU_PROVIDERS_ALLOW_UNTESTED=true overrides the check.

5. Gateway Notes

Success is decided by the gateway’s reply, not the HTTP status. Every reply goes through the provider’s own parser, so Novu’s activity feed shows the gateway’s reason.

Credential redaction

  • Before the reason is cut to 200 characters, the integration’s username and password are masked in all forms (as sent, URL/form/HTML-encoded, and as the Basic-auth token). Any password=-style value is also masked.

  • Transport errors (connection refused, reset, DNS, timeout) never reach a parser, but Novu stores whatever a send throws. register.js therefore wraps every DIGIT provider’s sendMessage and converts any rejection into a plain Error with:

    • a redacted message of at most 500 characters, and

    • no config, request, response, code or cause.

  • The message masks the username, password and every other credential except from, baseUrl, senderName, host and port. Example: jasmin request failed: connect ECONNREFUSED 10.0.0.5:1401

  • test/error-boundary.test.js checks this against refused, reset and HTTP 500 sockets.

Sender (from) field

Provider
Request
Accepted when…
Notes

SMSCountry

form-encoded User, passwd, mobilenumber (digits only), message, sid, mtype=N, DR=Y to the legacy bulk API (http://api.smscountry.com/SMSCwebservice_bulk.aspx unless Gateway URL is set)

the body starts OK:; the job id after it becomes Novu's message id

HTTP 200 is not success: a malformed request gets 200 and an ASP.NET error page. Accepted is not delivered: a message the operator drops (an unregistered DLT template) still gets OK:. The legacy bulk API only; a panel showing AuthKey/AuthToken is the REST API, which is not supported.

Ozeki

POST JSON {"messages":[{message_id, to_address, text, from_address?}]} to the HTTP API URL, HTTP Basic auth

response_code is SUCCESS, failed_count is 0 and the message's status is SUCCESS

Rejections, including a wrong password, come back as HTTP 200 with an error envelope. message_id is Novu's message id, echoed back. Ozeki has no delivery webhook, so accepted means submitted.

Jasmin

form-encoded username, password, to, from, content (or hex-content), coding, dlr=no to the Send URL (:1401/send)

the plain-text reply Success "<msgid>"

Failures carry a real status (400, 403, 412 or 500) and Error "<message>". Text outside the GSM 03.38 alphabet (Amharic, Arabic, emoji) is sent as UCS-2 (coding=8), with 70 characters per SMS segment instead of 160, so the same complaint message can cost two or three times as many segments. The provider picks the coding per message. Jasmin converts content to GSM 03.38 only for coding 0 and forwards it byte for byte otherwise, so UCS-2 text goes as hex-content, its UTF-16BE bytes in hex. That needs the Jasmin user's set_hex_content authorization, which Jasmin grants unless an operator revoked it (then every UCS-2 message fails with 403).

from is optional for Ozeki and Jasmin, in which case the gateway's or route's default sender is used. It is required for SMSCountry, which rejects an unregistered sender.

A blank optional field is omitted from the Novu credentials, so the provider default applies.

6. Legacy Cases

Providers created before these were native

Builds of this branch before the switch created SMSCountry and Ozeki providers as generic-sms integrations. Those SMSCountry integrations pointed at a novu-bridge adapter that no longer exists. Novu cannot change an integration's provider, so rotating one of them answers 400 NB_INVALID_PROVIDER. To replace one:

  1. Add a new provider of the same type.

  2. Select it on Channels.

  3. Delete the old one.

No 2.12 deployment has such an integration: 2.12 had no provider catalogue.

The legacy direct route

  • Enabled with novu.bridge.sms.provider=smscountry (host_vars novu_bridge_sms_provider).

  • The bridge posts to SMSCountry itself via SmsCountryDeliveryProvider, using env credentials (novu_bridge_smscountry_user / _password / _url).

  • It bypasses Novu: no credential store, activity log or Configurator management, and it doesn’t need DIGIT’s worker providers.

  • Failures show as NB_SMSCOUNTRY_REJECTED or NB_SMSCOUNTRY_UNREACHABLE.

  • It exists for 2.12 deployments. Use it or an SMSCountry provider on a channel, never both.

Provider selection at dispatch

On every dispatch, the bridge:

  1. Reads the tenant’s NOTIFICATIONS.Channel row at the state tenant (60 s cache).

  2. Treats the row’s provider field as the Novu integration identifier, looked up in the tenant’s own Novu organisation if it has one, otherwise in the shared account.

  3. Checks the selection against Novu’s integration list (cached, NOVU_BRIDGE_PROVIDER_AVAILABILITY_CACHE_TTL_MS, 60 s).

Recorded as SKIPPED / NB_PROVIDER_UNAVAILABLE (not triggered) when the provider is:

  • missing,

  • disabled, or

  • for the wrong channel.

SMS and WhatsApp both use Novu’s sms channel, so the catalogue type decides. A Twilio SMS or SMS-only gateway provider selected for WhatsApp is wrong-channel, and so is a Twilio WhatsApp provider selected for SMS.

Other rules

  • Only integrations in the Novu environment of the account’s API key count (NOVU_API_KEY for the shared account, the organisation’s own key for a workspace). Novu’s list includes both Development and Production, but a trigger uses only the key’s environment.

  • If Novu can’t be reached for the check, the bridge delivers as it otherwise would.

  • With no provider selected: the row’s gateway and the env fallbacks apply. A message that would go through Novu still needs at least one active integration that delivers the channel in the account it’s sent through. Otherwise Novu would accept the trigger and fail later (“Subscriber does not have an active integration”), so the bridge records SKIPPED / NB_PROVIDER_UNAVAILABLE instead of SENT.

    • For a workspace with its own organisation, the shared NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP pin does not apply.

    • An integration for another channel doesn’t count (e.g. Twilio WhatsApp doesn’t count for SMS).

    • An integration the bridge can’t identify (e.g. made by hand in Novu’s dashboard) does count.

  • The check can’t see whether the worker loads DIGIT’s providers. It relies on NOVU_BRIDGE_DIGIT_WORKER_PROVIDERS. With the flag off, selected SMSCountry, Ozeki or Jasmin providers are skipped.

Test send (POST /providers/test-send)

  • Runs the same check first, on the named integration, or on the channel’s Novu default if none is named. (A channel on the direct SMSCountry route isn’t checked against Novu.)

  • Where dispatch would record SKIPPED, the test is refused with 409 NB_PROVIDER_UNAVAILABLE, and nothing is sent.

  • An integration ID Novu doesn’t know at all returns 400 NB_PROVIDER_NOT_FOUND.

  • It reads Novu’s list fresh (no cache).

  • If the list can’t be read, the test is sent anyway, with a warning that it wasn’t checked.

  • Workspace tests are judged only against that organisation’s integrations:

    • its own provider passes;

    • a shared-account provider returns 400 NB_PROVIDER_NOT_FOUND;

    • with none named, it needs an active integration of its own for the channel (a workspace never uses the direct gateway).

7. Remove a Provider

Shared-account integrations are deployment-wide. POST /providers/_delete and _update with active: false return 409 NB_PROVIDER_IN_USE while a tenant still sends through the provider. For a workspace’s own organisation, only that workspace’s channel rows are checked, and the env pins don’t apply.

A provider is “in use” if:

  1. A channel row selects it, by identifier or Novu _id.

  2. It’s the WhatsApp pin: it’s the integration named by NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP, and some enabled WhatsApp channel has no provider selected.

  3. It’s the last active integration of its kind (SMS, WhatsApp or Email) and some enabled channel of that kind has no provider selected, so it relies on Novu’s default. This can be:

    • a legacy RAINMAKER-PGR.NotificationChannel row (which has no provider field),

    • a state with no rows running on NOVU_BRIDGE_CHANNELS_ENABLED, or

    • any tenant while the channel policy is off.

Exceptions to rule 3

  • A remaining WhatsApp integration doesn’t keep an SMS one deletable, and vice versa.

  • An SMS channel on the legacy direct route doesn’t count.

  • WhatsApp doesn’t count while NOVU_BRIDGE_INTEGRATION_ID_WHATSAPP is set (rule 2 covers it).

How it checks

  • Channel rows are read from MDMS at call time, once per state.

  • States checked: the request’s tenantId, every state the caller administers, every state the bridge has dispatched for since start-up, and the states that own the providers.

  • It fails closed: a state whose rows can’t be read causes a refusal, and an unreadable Novu list fails the call before anything changes.

8. Who may manage providers?

Workspace with its own Novu organisation

  • The Configurator sends ?tenantId=<workspace> on every provider call.

  • The bridge acts on that workspace’s organisation if the caller holds a role from NOVU_BRIDGE_PROXY_ADMIN_ROLES at the workspace’s root tenant. No NOVU_BRIDGE_PROVIDER_ADMIN_TENANTS entry is needed.

  • Anyone else gets 403 NB_TENANT_NOT_ALLOWED, including an admin of a state that owns the shared providers.

  • Reads with the selector need the workspace among the caller’s tenants.

  • The internal admin API (/tenants/{tenant}/providers) manages the same organisation for machine callers.

Everyone else (shared account)

Creating, updating, deleting and test-sending need a role from NOVU_BRIDGE_PROXY_ADMIN_ROLES, held at a state tenant that owns the deployment’s providers:

  • the state of NOVU_BRIDGE_CORE_SMS_DEFAULT_TENANT (set by the deploy to its state root), or

  • any state in NOVU_BRIDGE_PROVIDER_ADMIN_TENANTS (comma-separated, default empty).

Admins of any other root get 403 NB_TENANT_NOT_ALLOWED. If neither setting names a state, every such call is refused and the bridge logs a start-up warning. migrate-notifications.py --create-provider uses POST /providers, so log in at an owning state for that step.

Dispatch tools

/dispatch/_resolve and /dispatch/_dry-run need the same role at a state tenant:

  • The admin of the event tenant’s state root may run them, and so may an owning state’s admin for any tenant.

  • migrate-notifications.py plan previews each root through _resolve while logged in at that root.

  • _dry-run with "send": true is a real send through the shared providers, so like test-send it needs an owning state. The exception is when the event’s tenant has its own organisation and the caller administers it: then the send goes through that organisation.

9. Add a Provider

See adding-a-provider.md for a full walkthrough. This section is the reference.

One rule: one provider class in Novu, plus one catalogue entry. novu-bridge never carries gateway-specific code.

Step 1: Write the provider (novu-worker-providers)

Copy jasmin.js (form-encoded, plain-text reply) or ozeki.js (JSON). No image to build.

  1. Add <id>.js exporting:

    • PROVIDER_ID

    • the provider class (extends BaseProvider from ./novu; implements sendMessage(options, bridgeProviderData); returns { id, date })

    • the handler (extends BaseSmsHandler; buildProvider(credentials) maps credentials to config)

  2. Add the handler to loadHandlers() in register.js.

  3. Use only credential keys Novu’s API already stores: user, password, from, baseUrl, apiKey, secretKey, token, host, port. Novu drops any other key on save, so a new name would arrive empty.

  4. Add test/<id>.test.js and run ./run-tests.sh.

  5. Copy the runtime file to devops/deploy-as-code/charts/backbone-services/novu/files/novu-worker-providers/. The static contract test fails until it matches.

Provider rules

  • Decide success from the gateway’s reply, not the HTTP status. Pass validateStatus: () => true.

  • Throw if the gateway didn’t accept the message.

  • Mask credentials in any quoted gateway text (redactedSnippet from ./novu). Transport failures need no handling, because register.js redacts every error at the boundary.

  • Test every real reply shape: success, error string, HTML error page, empty body, rejection-as-200. Confirm each test fails when its behaviour is removed.

Step 2: Add the catalogue entry (ProviderCatalog)

  1. Add a type constant and include it in TYPES_LONGEST_FIRST, so no type prefix-matches a longer one.

  2. Add a NOVU_PROVIDER_* constant (the Novu provider ID, which can differ from the type ID) and a TYPE_BY_NOVU_SMS_PROVIDER entry. Every SMS type needs both, including upstream ones like Twilio. Without them, integrations made in Novu’s dashboard derive no type and can’t be rotated.

  3. Add the type’s channel to CHANNEL_BY_TYPE.

  4. DIGIT providers only: add the NOVU_PROVIDER_* constant to WORKER_NOVU_PROVIDERS, so the worker-provider flag hides and refuses it. Upstream providers stay out.

  5. Add the entry to allTypes(). Field keys must be the Novu provider’s credential keys:

Notes

  • Put operator-facing guidance (costs, encodings, API variant) in the field help; the Configurator shows it under the field.

  • The Configurator uses its own translation instead of the catalogue label for user, password, from, token, host, port, accountSid and secure. For example, user always reads “SMTP User”.

  • supportsVerify(true) enables Check status (POST /providers/verify), which only confirms the integration exists and is active.

  • supportsTestSend(true) enables Test (POST /providers/test-send), the only real proof the credentials work.

Step 3: Mirror and update tests

Mirror in local-setup/scripts/migrate-notifications.py:

  • CATALOG_CHANNEL, CATALOG_LABEL, CATALOG_REQUIRED, TYPES_LONGEST_FIRST, TYPE_BY_NOVU_SMS_PROVIDER

  • MOUNTED_PROVIDER_TYPES (DIGIT providers only)

Update the tests that pin the catalogue (otherwise mvn test, run-tests.sh and jest fail):

Applies to
Files

All providers

ProviderCatalogTest (provider ID, keys, type list); ProviderControllerGuardsTest (catalogue size, which types the switch hides/refuses)

DIGIT providers only

test/register.test.js (registered IDs); provider loop in test/error-boundary.test.js; sorted runtimeFiles list in deployment-contracts.test.ts

Python mirror

local-setup/tests/test_notification_seed_decisions.py

Not pinned by any test (easy to miss)

Type enums of ProviderType and ProviderCreateFromCatalog in both openapi.yaml copies

Step 4: Verify

  • GET /novu-adapter/v1/providers/catalog lists the new type.

  • Creating one without a required field returns 400 NB_INVALID_PROVIDER.

  • The created identifier maps back to the type.

  • Test delivers through a mock gateway that reproduces real reply formats (developer-guide.md), then through the real gateway.

When to bypass Novu: write a DeliveryProvider only if Novu’s worker cannot drive the gateway at all. You lose credential storage, the activity log and operator management.

10. Delivery Receipts for a New Gateway

service/receipts/ReceiptParser looks for a correlation ID and an outcome word anywhere in the payload (contract/outputs.md). A new gateway usually needs only:

  1. A Kong route for /novu-bridge/novu-adapter/v1/receipts/<gateway> (see novu-bridge-receipts-route and the auth-optional list in kong.yml).

  2. The shared secret.

Extend ID_KEYS, REF_KEYS, STATUS_KEYS or mapStatus only for field names these rules miss.

Note: the source’s table listing the six catalogue types was missing from the pasted text, so I left it out. If you can share it, I can add it to Section 1. I can also split this into separate GitBook pages (e.g. Operators, Deployers, Developers) if you’d like it audience-segmented.

Last updated

Was this helpful?