Requesting A Notification Send
NSS exposes two public API endpoints for sending a notification: one for sending a notification to a single user, and one for sending a notification to a batch of up to 100 users.
Request Headers
Bearer Token: Required.
The bearer token is stored in GCP secrets, reach out to Cloud Infra to have that secret added to your project.
Request ID: Optional.
UUID to identify the request and used as a distributed tracing ID
Idempotency Key: Optional.
UUID to deduplicate requests. For a given single request the same idempotency id should be included for each retry. The idempotency id has a time window of 7 days, retried requests beyond this window will not be idempotent.
Generate a consistent UUID for each unique request
Monolith example
idempotency_id = UuidUtils.hs_uuid_v5("#{job.id}>#{user_id_batch.to_json}")
API Endpoints
POST /v1/notifications
Request Body:
{
"notification_name": "string", // required – must match a configured notification
"notification_version": "string",// required – version of the notification config
"user_id": 123, // required – int64, recipient user ID
"attributes": { ... }, // optional – template data
"metadata": { ... } // optional – extra notification metadata
}
Response Body:
{
"data": {
"status_message": "string", // optional human-readable message
"status_code": "string" // required code for programmatic handling
}
}
POST /v1/notifications/batch
Request Body
{
"notification_name": "string", // required
"notification_version": "string", // required
"base_attributes": { ... }, // optional – shared template data
"base_metadata": { ... }, // optional – shared metadata
"items": [ // required, 1–100 items
{
"user_id": 123, // required – int64
"attributes": { ... }, // optional – merged with base_attributes
"metadata": { ... } // optional – merged with base_metadata
}
]
}
Response Body:
{
"data": {
"status_message": "string", // optional
"status_code": "string" // required
}
}
You can find the full OpenAPI spec for these endpoints here:
Code Examples
Curl
curl -s \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer apitoken" \
-X POST \
-d '{ "notification_name": "project_invitations", "notification_version": "1", "user_id": 125, "attributes": { "profile_id": 2, "project_id": 1 } }' \
localhost:5550/v1/notifications
Monolith
This is the Sidekiq worker used to send notifications in the monolith.
notification_name = "approve_job_posting"
notification_version = "1"
recipient_ids = [123, 456]
attributes = { "posting_id": 123 }
idempotency_id = UuidUtils.hs_uuid_v5("#{job.id}>#{recipient_ids.to_json}")
Notifications::NotificationSendingBatchWorker.perform_async(
notification_name,
version,
attributes,
recipient_ids,
idempotency_id
)
HAI
import { createNotificationClient } from 'packages/email/src/notification-client';
const response = await notificationClient.sendNotification({
notification_name: 'video_review_approval',
notification_version: '1',
user_id: profile.handshakeUserId,
attributes: {
project_id: projectId,
},
});