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
POST /novu-adapter/v1/providersreceives the request.The bridge validates the credentials against the catalogue.
It copies them into Novu’s credential keys (
ProviderCatalog.toNovuCredentials).It creates the Novu integration.
Flow when a message is sent
The bridge triggers the channel’s Novu workflow:
complaints-sms,complaints-whatsapporcomplaints-email.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 thenovutransport.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.
twilio-sms
SMS
twilio
accountSid, token, from
upstream Novu
twilio-whatsapp
twilio
accountSid, token, from
upstream Novu
smtp
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>.typeFromIdentifiermaps an identifier back to its type usingTYPES_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:
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.jsDIGIT_NOVU_PROVIDERS=requiredthe directory mounted read-only at
/opt/digit-novu-providers
This works because the Novu worker isn’t bundled.
register.jspatches the sameSmsFactorythe worker uses.
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
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_VERSIONSinregister.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:
The Configurator saves an SMSCountry, Ozeki or Jasmin provider.
The trigger is accepted, and the dispatch row reads
SENT.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,ozekiandjasminfromGET /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_UNAVAILABLEany 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
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:
Run the tests against the new image:
NOVU_TEST_IMAGE=ghcr.io/novuhq/novu/worker:<version> backend/novu-bridge/novu-worker-providers/run-tests.shFix any failures, add the version to
SUPPORTED_WORKER_VERSIONSinregister.js, and copy the runtime files to the chart.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.jstherefore wraps every DIGIT provider’ssendMessageand converts any rejection into a plainErrorwith: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,hostandport. Example:jasmin request failed: connect ECONNREFUSED 10.0.0.5:1401test/error-boundary.test.jschecks this against refused, reset and HTTP 500 sockets.
Sender (from) field
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:
Add a new provider of the same type.
Select it on Channels.
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_varsnovu_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_REJECTEDorNB_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:
Reads the tenant’s
NOTIFICATIONS.Channelrow at the state tenant (60 s cache).Treats the row’s
providerfield as the Novu integration identifier, looked up in the tenant’s own Novu organisation if it has one, otherwise in the shared account.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.
Other rules
Only integrations in the Novu environment of the account’s API key count (
NOVU_API_KEYfor 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_UNAVAILABLEinstead ofSENT.For a workspace with its own organisation, the shared
NOVU_BRIDGE_INTEGRATION_ID_WHATSAPPpin 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 with409 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:
A channel row selects it, by identifier or Novu
_id.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.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.NotificationChannelrow (which has no provider field),a state with no rows running on
NOVU_BRIDGE_CHANNELS_ENABLED, orany 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_WHATSAPPis 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_ROLESat the workspace’s root tenant. NoNOVU_BRIDGE_PROVIDER_ADMIN_TENANTSentry 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), orany 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 planpreviews each root through_resolvewhile logged in at that root._dry-runwith"send": trueis 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.
Add
<id>.jsexporting:PROVIDER_IDthe provider class (extends
BaseProviderfrom./novu; implementssendMessage(options, bridgeProviderData); returns{ id, date })the handler (extends
BaseSmsHandler;buildProvider(credentials)maps credentials to config)
Add the handler to
loadHandlers()inregister.js.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.Add
test/<id>.test.jsand run./run-tests.sh.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 (
redactedSnippetfrom./novu). Transport failures need no handling, becauseregister.jsredacts 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)
Add a type constant and include it in
TYPES_LONGEST_FIRST, so no type prefix-matches a longer one.Add a
NOVU_PROVIDER_*constant (the Novu provider ID, which can differ from the type ID) and aTYPE_BY_NOVU_SMS_PROVIDERentry. 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.Add the type’s channel to
CHANNEL_BY_TYPE.DIGIT providers only: add the
NOVU_PROVIDER_*constant toWORKER_NOVU_PROVIDERS, so the worker-provider flag hides and refuses it. Upstream providers stay out.Add the entry to
allTypes(). Field keys must be the Novu provider’s credential keys:
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_PROVIDERMOUNTED_PROVIDER_TYPES(DIGIT providers only)
Update the tests that pin the catalogue (otherwise mvn test, run-tests.sh and jest fail):
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/cataloglists 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.
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:
A Kong route for
/novu-bridge/novu-adapter/v1/receipts/<gateway>(seenovu-bridge-receipts-routeand the auth-optional list inkong.yml).The shared secret.
Extend ID_KEYS, REF_KEYS, STATUS_KEYS or mapStatus only for field names these rules miss.
Last updated
Was this helpful?