Quickstart

Get your first message published and delivered through npayload in five minutes.

What you will build

Before writing any code, here is the full picture of what happens when you publish a message through npayload:

Your app@npayload/node SDK

Edge layerOAuth 2.0 + DPoP, rate limiting

ChannelNamed message stream

Message storedImmutable, encrypted, audited

Fan-out + deliveryRoutes, retries, delivers

Dead letter queueOn failure after retries

Subscriber AYour endpoint

Subscriber BYour endpoint

The diagram above shows the complete event lifecycle:

Your app publishes a message using the @npayload/node SDK.
The edge layer authenticates your request with OAuth 2.0 + DPoP and applies rate limiting.
The message is routed to a channel, a named stream that organises your events.
The message is stored immutably with encryption and an audit trail.
The fan-out engine routes the message to every matching subscription.
Each subscription receives the message via webhook delivery with automatic retries.
If delivery fails after all retries, the message goes to the dead letter queue for inspection and replay.

By the end of this quickstart, you will have all of this running.

Prerequisites

Node.js 18+ installed
An npayload account (sign up at admin.npayload.com)

Get your credentials

Log in to admin.npayload.com
Create or select an Organisation
Create an App (for example, "my-first-app")
Navigate to Machine Credentials and register a new client
Copy your Client ID (starts with oac_) and HMAC Secret

Never expose your HMAC secret in client side code or public repositories. Store it in a secret vault such as AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault.

Install the SDK

npm install @npayload/node

pnpm add @npayload/node

yarn add @npayload/node

bun add @npayload/node

Initialise the client

The SDK handles the full OAuth 2.0 + DPoP flow automatically. You provide your credentials; the SDK manages token exchange, refresh, and proof-of-possession signing.

import { NPayloadAuth, NPayloadClient } from '@npayload/node';

const auth = new NPayloadAuth({
  clientId: process.env.NPAYLOAD_CLIENT_ID!,   // oac_...
  hmacSecret: process.env.NPAYLOAD_HMAC_SECRET!,
});

const npayload = new NPayloadClient({
  auth,
  environment: 'development',
});

This corresponds to the Your app and Edge layer in the architecture diagram above. Every API call from this point forward is authenticated and rate-limited at the edge before reaching your instance.

Create a channel

A channel is a named message stream. All messages published to a channel are stored immutably and delivered to every subscription.

const channel = await npayload.channels.create({
  name: 'orders',
  description: 'Order events for my app',
  privacy: 'standard',  // 'standard' | 'hybrid' | 'e2e'
});

console.log('Channel created:', channel.gid);

npayload supports three privacy modes:

Standard: plaintext (fastest, simplest)
Hybrid: metadata visible, payload encrypted
E2E: zero-knowledge encryption where npayload cannot read your data

Publish a message

When you publish, the message is stored immutably and the fan-out engine routes it to all matching subscriptions.

const message = await npayload.messages.publish({
  channel: 'orders',
  payload: {
    event: 'order.created',
    orderId: 'ord_12345',
    customer: { id: 'cust_abc', email: 'customer@example.com' },
    total: 59.98,
    createdAt: new Date().toISOString(),
  },
});

console.log('Message published:', message.gid);

Create a subscription

A subscription tells npayload where to deliver messages. You can create multiple subscriptions per channel; each one receives every message independently.

const subscription = await npayload.subscriptions.create({
  channel: 'orders',
  name: 'fulfillment-webhook',
  type: 'webhook',
  endpoint: {
    url: 'https://your-service.com/webhooks/orders',
    method: 'POST',
  },
});

console.log('Subscription created:', subscription.gid);

Receive and verify webhooks

Set up an endpoint to receive messages. Always verify the HMAC signature before processing.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/orders', (req, res) => {
  // Verify the webhook signature
  const isValid = npayload.webhooks.verify(
    req.body,
    req.headers['x-npayload-signature'] as string,
    process.env.WEBHOOK_SECRET!
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the message
  const { payload } = req.body;
  console.log('Received event:', payload.event);
  console.log('Order ID:', payload.orderId);

  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
});

app.listen(3000);

Return 200 immediately and process the message asynchronously. npayload retries on non-2xx responses with exponential backoff (1s, 30s, 5m, 30m, 2h). After all retries are exhausted, the delivery is moved to the dead letter queue.

The delivery lifecycle

Here is what npayload does behind the scenes every time you publish:

Publish

Fan-out

Deliver

Webhook

Dead letter queueOn failure

Stage	What happens
Publish	Your message is validated, encrypted (if applicable), and stored immutably
Fan-out	The message is routed to every subscription matching the channel
Deliver	Each subscription endpoint receives an HTTP POST with retries on failure
Webhook	On success, delivery is marked complete with a full audit trail
DLQ	On failure after all retries, the message goes to the dead letter queue for inspection, debugging, and replay

Complete example

Here is everything together in a single script:

import { NPayloadAuth, NPayloadClient } from '@npayload/node';

async function main() {
  const auth = new NPayloadAuth({
    clientId: process.env.NPAYLOAD_CLIENT_ID!,
    hmacSecret: process.env.NPAYLOAD_HMAC_SECRET!,
  });

  const npayload = new NPayloadClient({
    auth,
    environment: 'development',
  });

  // Create a channel
  const channel = await npayload.channels.create({
    name: 'notifications',
    description: 'User notifications',
  });

  // Create a subscription
  await npayload.subscriptions.create({
    channel: 'notifications',
    name: 'email-service',
    type: 'webhook',
    endpoint: {
      url: 'https://email-service.example.com/notify',
    },
  });

  // Publish messages
  for (let i = 0; i < 3; i++) {
    const message = await npayload.messages.publish({
      channel: 'notifications',
      payload: {
        type: 'welcome',
        userId: `user_${i}`,
        message: 'Welcome to npayload!',
      },
    });
    console.log(`Published message ${i + 1}:`, message.gid);
  }

  console.log('Done. Check your webhook endpoint for deliveries.');
}

main().catch(console.error);

Troubleshooting

Problem	Solution
"Invalid credentials"	Ensure your client ID starts with `oac_` and the HMAC secret matches
"Channel not found"	Create the channel first with `channels.create()`
Webhook not receiving	Verify the URL is publicly accessible and uses HTTPS

Next steps

How it works

Understand the full architecture

Authentication

OAuth 2.0 + DPoP deep dive

API reference

Explore all endpoints

Webhooks

Delivery, retries, and signatures

Was this page helpful?

Quickstart

How it works

Authentication

API reference

Webhooks

On this page