Quickstart Guides

Java / Spring Boot Quickstart

Complete end-to-end guide to send multi-channel notifications from a Java or Spring Boot application — from API key generation to template creation, event triggering, and delivery verification.

1. Sign Up & Get API Key

Register at https://app.hubnest.io. Go to Developer → API Keys → Generate New Key. Copy rawKey (hn_live_...) — shown only once. Add to application.properties: hubnest.api-key=hn_live_xxxxx

Store rawKey immediately

The rawKey is hashed before storage and shown only once. Add it to your Spring Boot application.properties or application.yml immediately.

2. Create a Subscriber

Create a subscriber to represent a user. Each subscriber maps your user's email and phone to a subscriberId for targeted delivery.

setup/CreateSubscriber.sh

bash

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

2 -H "Authorization: Bearer $HUBNEST_API_KEY" \

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": false, "push": false }

9 }'

10# Returns: { "id": "<subscriber-uuid>", ... }

3. Create a Notification Template

Create templates at Developer → Templates → New Template. Or use the REST API — type is the identifier referenced in Workflows, id (UUID) is used in direct sends.

setup/CreateTemplate.sh

bash

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

2 -H "Authorization: Bearer $HUBNEST_API_KEY" \

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!",

9 "variablesSchema": ["customerName"]

10 }'

11# Returns: { "id": "<template-uuid>", "type": "user.welcome", ... }

4. Connect a Channel Provider

Go to Developer → Channels → Add Provider at https://app.hubnest.io. Use Demo Email for instant testing, or connect AWS SES, SendGrid, Twilio, MSG91, WhatsApp, FCM, or APNs for production.

5. Add Spring Boot Dependencies

Add RestTemplate or WebClient to your Spring Boot project. RestTemplate is available in spring-boot-starter-web:

pom.xml (excerpt)

xml

1<dependency>

2 <groupId>org.springframework.boot</groupId>

3 <artifactId>spring-boot-starter-web</artifactId>

4</dependency>

6

7hubnest.api-key=hn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

8hubnest.base-url=https://api.hubnest.io

6. Create HubNestService.java

Create a Spring service that wraps all HubNest API calls:

src/main/java/com/example/HubNestService.java

java

1package com.example;

3import org.springframework.beans.factory.annotation.Value;

4import org.springframework.http.*;

5import org.springframework.stereotype.Service;

6import org.springframework.web.client.RestTemplate;

7import java.util.Map;

9@Service

10public class HubNestService {

12 @Value("${hubnest.api-key}")

13 private String apiKey;

15 @Value("${hubnest.base-url}")

16 private String baseUrl;

18 private final RestTemplate restTemplate = new RestTemplate();

20 private HttpHeaders headers() {

21 HttpHeaders headers = new HttpHeaders();

22 headers.set("Authorization", "Bearer " + apiKey);

23 headers.setContentType(MediaType.APPLICATION_JSON);

24 return headers;

25 }

27 // Trigger event — evaluates Rules + Workflows

28 public Map<String, Object> triggerEvent(String eventName, String subscriberId, String email, Map<String, Object> payload) {

29 String body = String.format(

30 "{\"eventName\":\"%s\",\"to\":{\"subscriberId\":\"%s\",\"email\":\"%s\"},\"payload\":%s}",

31 eventName, subscriberId, email, payload.toString().replace("=", ":")

32 );

33 HttpEntity<String> entity = new HttpEntity<>(body, headers());

34 ResponseEntity<Map> res = restTemplate.postForEntity(baseUrl + "/api/v1/events", entity, Map.class);

35 // Response: { "status": "processed", "workflowsTriggeredCount": 1, "ruleMatched": false }

36 return res.getBody();

37 }

39 // Direct send — bypasses Rules & Workflow engine

40 public Map<String, Object> sendDirect(String recipient, String channel, String templateId, Map<String, String> variables) {

41 String body = String.format(

42 "{\"recipient\":\"%s\",\"channel\":\"%s\",\"templateId\":\"%s\",\"category\":\"TRANSACTIONAL\"}",

43 recipient, channel, templateId

44 );

45 HttpEntity<String> entity = new HttpEntity<>(body, headers());

46 ResponseEntity<Map> res = restTemplate.postForEntity(baseUrl + "/api/v1/notifications/send", entity, Map.class);

47 return res.getBody(); // { "notificationId": "...", "status": "..." }

48 }

49}

7. Direct Send & Bulk Send

Use the direct send API to bypass Rules/Workflows, or the campaign API to fan out to many recipients via Kafka background queue:

BulkCampaign.sh

bash

1# Bulk campaign to multiple recipients

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

3 -H "Authorization: Bearer $HUBNEST_API_KEY" \

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

5 -d '{

6 "channel": "EMAIL",

7 "templateId": "<your-template-uuid>",

8 "recipients": ["user1@example.com", "user2@example.com", "user3@example.com"],

9 "category": "MARKETING"

10 }'

11# Response: { "message": "Fanned out 3 messages in campaign successfully via background queue.", "totalRecipients": "3" }

8. Verify Delivery in Logs

After calling triggerEvent() or sendDirect(), go to Developer → Logs at https://app.hubnest.io to see delivery status, provider used, latency, and wallet cost per notification. Configure Webhooks at Developer → Webhooks for real-time delivery callbacks.

Use ObjectMapper for robust JSON

For production use, replace String.format() JSON construction with Jackson ObjectMapper to safely serialize payload maps without escaping issues.

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?