NotifyHub Getting started
Home · Docs · Getting started
Onboarding

Bring a service onto NotifyHub without leaking provider complexity.

The client onboarding flow is intentionally narrow: create a client, assign channels, create templates, and send requests with the client API key. The control plane handles the rest.

Context

Why clients use the control plane

Before NotifyHub

Every service had to know provider credentials, template rendering rules, retry behavior, and callback handling.

With NotifyHub

The client submits a canonical notification request and the platform resolves providers, templates, policies, and delivery attempts centrally.

Auth

Understand the two keys

Key Used by Can do
Client API key The upstream service that sends notifications Submit notification requests and read its own request status
Admin API token Operators and automation Create, patch, disable, and inspect platform records

Important The client API key is generated when a client is created. The admin token is configured by the operator and must stay private.

Step 1

Provision the client

Use the admin API to create the client identity and define which channels the service can use.

POST /v1/clients
X-Notification-Admin-Token: <admin token>
{
  "tenant_id": "tenant-a",
  "client_name": "billing-service",
  "allowed_channels": ["email", "sms", "whatsapp", "push", "webhook"],
  "enabled": true
}

The response includes:

  • the persisted client row
  • a client API key to store in the upstream service
Step 2

Send the first notification request

Use the client API key when a service calls the control plane. The payload should describe intent, not provider details.

POST /v1/notification-requests
Authorization: Bearer <client api key>
{
  "idempotency_key": "billing-2026-06-18-001",
  "event_name": "login.otp",
  "template_key": "<template_key>",
  "language_code": "en",
  "channels": ["whatsapp"],
  "recipient": { "phone": "<recipient_phone>" },
  "variables": { "otp": "<otp>" },
  "metadata": { "source": "<client_name>" }
}
Rule of thumb Clients should not send provider usernames, passwords, signatures, or media upload details. Those stay inside the control plane.
Step 3

Observe the lifecycle

Request record

Use GET /v1/notification-requests/{requestID} to see accepted, processing, dispatched, delivered, failed, or suppressed states.

Delivery attempts

Each channel attempt is stored separately so retries and fallbacks are visible in the database and API.

Callbacks

Provider callbacks update the delivery attempt and flow into normalized lifecycle events.

Webhooks

Downstream systems can subscribe to lifecycle events through webhook subscriptions.