Email
Transactional email
What the client sends
A template key, recipient email, variables, and a channel list that includes email.
What the platform does
Looks up the email template, renders subject and body, picks a provider binding, and records the delivery attempt.
Callback behavior
Email providers that support delivery callbacks mark the delivery attempt delivered or failed; providers without callbacks still work.
Common use case
OTP, receipts, password resets, and workflow notifications.
End-to-end example
- 1. Admin config Create a template for email, select a sender account, and define any callback route if the provider supports delivery webhooks.
- 2. Client request The client sends a notification request with
channels: ["email"], a template key, a recipient email, and variables.
- 3. Delivery The worker renders the template, sends the provider request, and stores the delivery attempt.
- 4. Callback Delivery updates return as normalized attempt status changes and can fan out to downstream webhook subscriptions.
SMS
OTP and short alerts
Template and language
SMS templates can have language-specific variants. The control plane falls back to English when a requested language is missing.
Provider support
The same channel can use Gupshup or Karix bindings. Provider credentials stay inside provider accounts and secret refs.
Callback behavior
Provider delivery callbacks update the delivery attempt status. Unsupported callback shapes are normalized in the gateway before they reach storage.
Best practice
Keep SMS bodies short, explicit, and template-driven. Use the request metadata for campaign or source tags, not provider internals.
End-to-end example
- 1. Admin config Create the SMS template, configure a provider account, and add the callback route if the provider posts delivery receipts.
- 2. Client request The client sends a notification request with
channels: ["sms"], a template key, a phone number, and language code.
- 3. Delivery The worker resolves the correct language template, chooses a healthy provider binding, and sends the SMS.
- 4. Callback The callback gateway normalizes the provider receipt and updates the delivery attempt status.
WhatsApp
Templates, media, and replies
What the client sends
Send the WhatsApp channel plus the template key and language code. If media is involved, the template metadata in the control plane defines the media type and provider-specific template name.
What the platform does
Resolves the template, chooses the provider binding, and sends a provider-compliant request shape without exposing provider details to the client service.
Replies and inbound messages
Inbound messages are treated as channel events. They are stored in the control plane and can be forwarded to downstream systems as normalized lifecycle events.
Media handling
Media support depends on the provider and the template metadata. The client still uses the same NotifyHub request model whether the payload is text, image, or video.
End-to-end example
- 1. Admin config Create the WhatsApp template, store the provider-specific template name and media metadata, and register the callback route.
- 2. Client request The client sends a notification request with
channels: ["whatsapp"], a template key, a phone number, and language code.
- 3. Delivery The worker resolves the template, applies the provider binding, and sends the WhatsApp message in the provider-compliant format.
- 4. Callback or reply Delivery receipts and inbound replies return through the callback gateway, are normalized, and are stored as channel events.
POST /v1/notification-requests
{
"event_name": "login.otp",
"template_key": "<template_key>",
"language_code": "en",
"channels": ["whatsapp"],
"recipient": { "phone": "<recipient_phone>" },
"variables": { "otp": "<otp>" }
}
Push
FCM-backed push notifications
What the client sends
Device token, template key, variables, and channel. The FCM service account is resolved by the connector from mounted secrets or secret references.
What the platform does
The push connector loads the service account, builds the FCM message, and stores the delivery attempt with the provider response.
Invalid token handling
Invalid or expired tokens should be treated as failed attempts and surfaced in the delivery record so the client can prune them.
Typical use case
App notifications, passwordless login, delivery updates, and operational alerts.
End-to-end example
- 1. Admin config Mount the FCM service account or secret reference, create the push provider account, and keep the device token out of the provider config.
- 2. Client request The client sends a request with
channels: ["push"], a template key, and a device token.
- 3. Delivery The push connector loads the service account, builds the FCM payload, and records the provider response.
- 4. Follow-up Push usually ends with the provider response, but if the provider reports invalid tokens, the attempt is marked failed so the client can prune them.
Webhook
Notify downstream systems with lifecycle events
Outbound webhook
Webhook subscriptions receive normalized events such as accepted, delivered, failed, or replayed notifications.
Why it exists
It lets another service observe what happened without connecting directly to provider-specific callback formats.
End-to-end example
- 1. Admin config Create a webhook subscription for the target system that should receive lifecycle events.
- 2. Client request The client sends a notification request through any supported channel.
- 3. Lifecycle event The control plane stores the request and delivery attempt data, then emits normalized lifecycle updates internally.
- 4. Webhook delivery The subscription receives the normalized event, independent of the original provider shape.
Integration tip
Use webhook subscriptions when you want a separate system to mirror delivery state, audit trails, or analytics.
