Getting Started

What is HubNest?

API-first multi-channel notification infrastructure for message routing, workflow automation, dynamic digesting, and user preferences. Get from zero to sending your first notification in under 10 minutes.

1. Create a HubNest Account

Sign up or log in at https://app.hubnest.io. On registration, you receive a dedicated tenant workspace with isolated secrets, encrypted credentials, and a pre-configured Demo Email and Demo SMS provider so you can test immediately.

Isolated Multi-Tenant Space

Every organization receives a dedicated tenant space. All provider secrets (API keys, tokens, p8 keys) are encrypted using AES-256 field encryption before storage. No plain-text secrets are ever persisted.

2. Understand the Architecture

HubNest sits between your application backend and external delivery networks (AWS SES, Twilio, Meta WhatsApp, FCM, APNs). Every event flows through the same 5-stage pipeline:

architecture/pipeline.txt

text

1[Your Backend App]

2 │ POST /api/v1/events

3 ▼

4[HubNest API Gateway] ←── API Key Auth

5 │ Rule Engine evaluation → Workflow Engine evaluation

6 ▼

7[Kafka Event Queue]

8 │ Background worker picks up job

9 ▼

10[Provider Router] ←── Health score + failover

11 ▼

12[Channel Adapters] ──► AWS SES / Twilio / Meta WhatsApp / FCM / APNs

13 │ Delivery response

14 ▼

15[Delivery Log + Webhook Callback]

3. Generate Your API Key

Go to https://app.hubnest.io → Developer → API Keys → Generate New Key. Give it a name (e.g. "Production Backend"), select scopes (["send"]), and choose environment (DEV / STAGING / PROD). Copy the rawKey immediately — it starts with hn_live_ and is shown only once.

rawKey shown only once

The rawKey (hn_live_...) is hashed before storage. It is returned only in this create response. If you lose it, you must revoke and generate a new key. Store it in your environment variables immediately.

api-keys/generate.sh

bash

1# Generate an API key via REST API

2curl -X POST "https://api.hubnest.io/developer/api-keys" \

3 -H "Authorization: Bearer <your-jwt-token>" \

4 -H "Content-Type: application/json" \

5 -d '{

6 "name": "Production Backend",

7 "scopes": ["send"],

8 "environment": "PROD"

9 }'

11# Response:

12# {

13# "id": "<uuid>",

14# "name": "Production Backend",

15# "rawKey": "hn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

16# "scopes": ["send"],

17# "environment": "PROD"

18# }

19# ⚠️ rawKey is shown ONLY ONCE — copy it now and store in your .env file

4. Create a Subscriber

A subscriber represents a user in your system. Create one before sending notifications so HubNest can resolve recipient details from a subscriberId. Go to Developer → Subscribers → Add Subscriber, or use the REST API:

externalId = your user ID

Set externalId to your own system user ID (e.g. from your auth database). This links HubNest subscribers to your users. channelPrefs controls which channels the user can receive on — set false to opt them out of a channel.

subscribers/create.sh

bash

1curl -X POST "https://api.hubnest.io/developer/subscribers" \

2 -H "Authorization: Bearer hn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "externalId": "user_12345",

6 "email": "user@example.com",

7 "phone": "+919876543210",

8 "channelPrefs": { "email": true, "sms": true, "whatsapp": true, "push": true }

9 }'

11# Response:

12# { "id": "<subscriber-uuid>", "externalId": "user_12345", "email": "user@example.com", ... }

13# Save the subscriber UUID — pass it as subscriberId in all event triggers

5. Create a Notification Template

Templates define the content of your notifications with dynamic {{variableName}} placeholders. Go to Developer → Templates → New Template, or use the REST API:

Variables are auto-extracted

If you omit variablesSchema, HubNest auto-extracts variable names from {{variableName}} placeholders in the body. The template type field (e.g. "user.welcome") is also used in Workflow SEND_ACTION nodes to reference this template.

templates/create.sh

bash

1curl -X POST "https://api.hubnest.io/developer/templates" \

2 -H "Authorization: Bearer hn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "type": "user.welcome",

6 "channel": "EMAIL",

7 "category": "TRANSACTIONAL",

8 "body": "Hi {{customerName}}, welcome to HubNest! Login here: {{loginUrl}}",

9 "variablesSchema": ["customerName", "loginUrl"]

10 }'

12# Response:

13# { "id": "<template-uuid>", "type": "user.welcome", "channel": "EMAIL", "version": 1, ... }

14# Save the template UUID — use it as templateId in direct notification sends

6. Connect a Channel Provider

Connect at least one delivery provider so HubNest knows where to route notifications. Go to Developer → Channels → Add Provider:

Demo providers for immediate testing

If you just want to test without real provider credentials, use the built-in Demo Email and Demo SMS providers. They are active by default and work immediately after account creation.

Email: Choose AWS SES (AKIA:secret format) or SendGrid (SG. API key). See Email Provider docs.
SMS: Choose Twilio (accountSid:authToken) or MSG91 (authkey + DLT fields). See SMS Provider docs.
WhatsApp: Use Meta Embedded Signup or enter Access Token + Phone Number ID + WABA ID manually. See WhatsApp docs.
Push: Upload Firebase Service Account JSON for FCM, or paste .p8 PEM key + Key ID + Team ID + Bundle ID for APNs.
Demo Providers: Pre-configured demo Email and SMS providers are available out of the box for testing — no setup needed.

7. Trigger Your First Notification

Fire an event from your backend — HubNest evaluates all active Rules and Workflows and dispatches matching notifications automatically:

events/trigger-first.sh

bash

1curl -X POST "https://api.hubnest.io/api/v1/events" \

2 -H "Authorization: Bearer hn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "eventName": "user.welcome",

6 "to": {

7 "subscriberId": "<subscriber-uuid>",

8 "email": "user@example.com"

9 },

10 "payload": {

11 "customerName": "Rahul Sharma",

12 "loginUrl": "https://yourapp.com/login"

13 }

14 }'

16# Response:

17# {

18# "status": "processed",

19# "eventName": "user.welcome",

20# "ruleMatched": false,

21# "workflowsTriggeredCount": 1

22# }

23# workflowsTriggeredCount: how many Workflows matched and ran

24# ruleMatched: whether any Rule also fired

8. Verify Delivery in Logs

Go to Developer → Logs to see every notification dispatched, its delivery status, latency, provider used, and cost. Each notification has a unique notificationId for tracking. You can also configure Webhooks at Developer → Webhooks to receive real-time DELIVERED/FAILED callbacks at your own endpoint.

Real-time delivery monitoring

The Logs tab shows provider-level delivery status, raw payloads sent to carriers, and wallet cost breakdown per message. Set up a Webhook endpoint to receive instant delivery callbacks in your own backend.

Next steps

AWS SES Email

Configure AWS SES IAM keys, verified domains, and sending rate limits.

SendGrid Email

Connect SendGrid API Keys and verified sender identities.

Twilio SMS Provider

Connect Twilio Account SID, Auth Token, and phone numbers.

WhatsApp Business

Connect Meta WhatsApp Cloud API access tokens and phone number IDs.

Was this guide helpful?