Node.js SDK
@pushizo/node — Node.js ≥ 20, ESM, types derived from OpenAPI; notifications, users, events, webhook signature verification, journeys, and the entire public API.
@pushizo/node is for server-side use only (never embed the API key in a client). It uses the built-in fetch, retries with exponential backoff, automatic idempotency keys, and the @pushizo/api-client types.
Installation and initialization
npm install @pushizo/nodeimport { Pushizo } from '@pushizo/node';
const hs = new Pushizo({
apiKey: process.env.HS_API_KEY!, // hs_live_… (Organization → API keys)
appId: process.env.HS_APP_ID, // used when a call doesn't pass appId
baseUrl: 'https://api.pushizo.com', // local: http://localhost:4000
maxRetries: 3, // exponential backoff for 429/5xx
timeoutMs: 30_000,
autoIdempotencyKey: true, // automatic UUID for notifications.create
});Sending notifications
const result = await hs.notifications.create({
idempotency_key: `order-${order.id}`,
target: { include_aliases: { external_id: [userId] } },
headings: { tr: 'Siparişiniz yola çıktı', en: 'Your order has shipped' },
contents: { tr: '…', en: '…' },
url: `https://pushizo.com/orders/${order.id}`,
data: { order_id: order.id },
channels: ['ios_push', 'android_push', 'web_push'],
send_after: new Date(Date.now() + 60_000).toISOString(),
});
// result.id (msg_…), result.status, result.recipients_estimate, result.external_id_missing
await hs.notifications.get(result.id);
await hs.notifications.list({ limit: 50, status: 'completed' });
await hs.notifications.cancel(result.id);
await hs.notifications.deliveries(result.id, { limit: 100 });
await hs.notifications.estimate({ target: { included_segments: ['seg_…'] } });The same idempotency_key with the same body returns the same response; a different body returns 409. An empty target returns 422 HS_NO_RECIPIENTS.
Email, SMS, and notification inbox
await hs.notifications.create({
idempotency_key: `shipped-${order.id}`,
target: { include_aliases: { external_id: [userId] }, channels: ['email', 'sms'] },
contents: { tr: 'Siparişin kargoda', en: 'Your order shipped' }, // SMS body
email_subject: 'Your order is on its way',
email_mjml: mjmlSource, // or email_body (ready-made HTML)
email_preheader: 'Your tracking number is inside',
email_from_name: 'Store', email_from_address: 'no-reply@pushizo.com', email_reply_to_address: 'support@pushizo.com',
sms_from: 'STORE',
add_to_inbox: true, inbox_ttl: 7 * 86_400,
});Field meanings: Messaging. Types come from OpenAPI via CreateNotificationInput.
Users, subscriptions, events, channels
await hs.users.upsert({ external_id: 'user_42', tags: { plan: 'pro' }, language: 'tr' });
await hs.users.getByExternalId('user_42');
await hs.users.update('external_id', 'user_42', { tags: { plan: 'free' } });
await hs.users.addAliases('external_id', 'user_42', { crm_id: 'C-1' });
await hs.users.addSubscription('external_id', 'user_42', { channel: 'email', token: 'a@b.c' });
await hs.users.delete('external_id', 'user_42');
await hs.users.list({ q: 'user_', limit: 20 });
await hs.users.search({ definition: { all: [{ field: 'tags.plan', op: 'eq', value: 'pro' }] }, limit: 50 });
await hs.subscriptions.get('sub_…'); await hs.subscriptions.update('sub_…', { opted_in: false });
await hs.subscriptions.setOwner('sub_…', 'user_42'); await hs.subscriptions.delete('sub_…');
await hs.events.send([{ external_id: 'user_42', name: 'purchase', properties: { sku: 'A1' }, value: 49.9, occurred_at: new Date().toISOString() }]);
await hs.channels.list(); await hs.channels.validate('android_push');
await hs.apps.list(); await hs.organization.get(); await hs.organization.usage({ days: 30 });Suppression list
const page = await hs.suppressions.list({ channel: 'email', reason: 'bounce', limit: 50 });
// page.data[i] → { id, channel, value_masked: 'a***e@pushizo.com', reason, source, expires_at }; page.next_cursor, page.has_more
const s = await hs.suppressions.create({ channel: 'sms', value: '+905321234567', reason: 'manual', note: 'customer request' });
await hs.suppressions.remove(s.id);Identity verification
const hash = Pushizo.identityHash(process.env.HS_SDK_SECRET!, externalId); // HMAC-SHA256
res.json({ external_id: externalId, identity_hash: hash }); // client SDK: login(externalId, hash)Webhooks
Endpoint management: hs.webhooks.list / create / get / update / delete / rotateSecret / test / deliveries / replay (admin). On the receiving side, verify the signature against the raw body:
import express from 'express';
import { constructWebhookEvents, WebhookSignatureError } from '@pushizo/node';
app.post('/hooks/pushizo', express.raw({ type: 'application/json' }), (req, res) => {
try {
const events = constructWebhookEvents({ payload: req.body, header: req.headers['pushizo-signature'], secret: process.env.HS_WEBHOOK_SECRET! });
for (const event of events) enqueue(event); // deduplicate using event.id (Pushizo-Event-Id)
res.sendStatus(204);
} catch (err) {
if (err instanceof WebhookSignatureError) return res.status(400).send(err.reason);
throw err;
}
});Details: Webhooks.
Journeys
const journey = await hs.journeys.create({ name: 'Post-purchase' });
await hs.journeys.saveDraft(journey.id, { graph: { nodes, edges }, settings: { re_entry: { mode: 'never' } } });
const { version, issues } = await hs.journeys.publish(journey.id);
const { entered, run } = await hs.journeys.triggerRun(journey.id, { external_id: 'u-1', context: { order_id: 'o-42' } });
await hs.journeys.stats(journey.id, { version });
await hs.journeys.listForUser('external_id', 'u-1');Lifecycle: pause, resume, archive, duplicate; updateNode, versions, exitRun. Graph format: Journeys.
All resources
The SDK covers every public operation in api/openapi.yaml (a coverage test maps each operation to a method): organization, apps, notifications (including history, exportEvents, estimate), users (getIdentity, export, search), subscriptions (getUserIdentity, updateByToken), events (including definitions), channels, suppressions, webhooks, segments, templates (copyToApp), campaigns (variantStats, selectWinner), journeys, inAppMessages, inbox, preferences, analytics (format: 'csv'), exports, imports (multipart), apiKeys (rotate). For paginated endpoints, use the hs.paginate(...) async iterator.
Errors
import { PushizoError } from '@pushizo/node';
try { … } catch (e) {
if (e instanceof PushizoError) { e.status; e.code; e.requestId; e.details; e.retryable; }
}Codes: error catalog.
Retry policy
Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most maxRetries times. To avoid double-processing requests that aren't safe to repeat on the server, the rule depends on the HTTP method:
| Condition | GET, HEAD, OPTIONS, PUT, DELETE | POST, PATCH |
|---|---|---|
429 | Retried | Retried (the request was rejected before processing) |
5xx, timeout, connection dropped after sending | Retried | Only with an Idempotency-Key |
Request never sent (ECONNREFUSED, ENOTFOUND/EAI_AGAIN DNS error, ENETUNREACH/EHOSTUNREACH, connect timeout) | Retried | Retried |
Other 4xx | Not retried | Not retried |
On a 5xx or a network error after sending, the server may have processed the request; retrying a POST/PATCH without a key can produce a duplicate notification or record. notifications.create and users.upsert generate an automatic UUID when no key is given (unless automatic keys are disabled), so these two calls are safe to retry. notifications.create carries the key in the body's idempotency_key field; that counts too. If you want another POST/PATCH call to be retried as well, pass the key yourself: hs.users.upsert(body, appId, { idempotencyKey: 'crm-42' }) or notifications.create({ idempotencyKey, … }). Retries send the same key; the API answers a repeat with the same key within 24 hours with the original response.
Windows (WNS)
WNS notifications for Windows apps associated with the Microsoft Store — no package required; the channel URI is written to the SDK registration endpoint.
PHP SDK
pushizo/pushizo-php — PHP ≥ 8.1, only ext-curl and ext-json; notifications, users, events, webhook signature verification, journeys, and the entire public API. Laravel example included.