PushizoDocs
SDK guides

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/node
import { 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:

ConditionGET, HEAD, OPTIONS, PUT, DELETEPOST, PATCH
429RetriedRetried (the request was rejected before processing)
5xx, timeout, connection dropped after sendingRetriedOnly with an Idempotency-Key
Request never sent (ECONNREFUSED, ENOTFOUND/EAI_AGAIN DNS error, ENETUNREACH/EHOSTUNREACH, connect timeout)RetriedRetried
Other 4xxNot retriedNot 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.

On this page