Embedding the Portal

This guide walks you through integrating Nahook's Developer Portal into your application so your customers can manage their own webhook endpoints.

Prerequisites

A Nahook workspace on the Pro plan or above
A Management Token (create one)

Step 1: Create an Application

An application represents one of your customers. Create one via the Management API:

curl -X POST https://api.nahook.com/management/v1/workspaces/ws_YOUR_ID/applications \
  -H "Authorization: Bearer nhm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "metadata": {
      "customerId": "cust_123"
    }
  }'

const response = await fetch(
  "https://api.nahook.com/management/v1/workspaces/ws_YOUR_ID/applications",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer nhm_YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Acme Corp",
      metadata: { customerId: "cust_123" },
    }),
  },
);

const app = await response.json();
// { id: "app_abc123", name: "Acme Corp", ... }

Save the id — you'll use it to create portal sessions.

Step 2: Create a Portal Session

When your customer wants to manage their webhooks, create a portal session:

curl -X POST https://api.nahook.com/management/v1/workspaces/ws_YOUR_ID/applications/app_abc123/portal \
  -H "Authorization: Bearer nhm_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor",
    "expiresInMinutes": 60,
    "metadata": {
      "userId": "usr_456",
      "email": "[email protected]"
    }
  }'

const session = await fetch(
  "https://api.nahook.com/management/v1/workspaces/ws_YOUR_ID/applications/app_abc123/portal",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer nhm_YOUR_TOKEN",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      role: "editor",
      expiresInMinutes: 60,
      metadata: {
        userId: "usr_456",
        email: "[email protected]",
      },
    }),
  },
);

const { portalUrl, code, expiresAt } = await session.json();
// portalUrl: "https://portal.nahook.com/s/{code}"
// code: "base64url_encoded_code"
// expiresAt: "2026-03-31T01:00:00.000Z"

Step 3: Redirect Your Customer

Send your customer to the portalUrl. They'll exchange the one-time code for a session automatically.

// In your backend route handler
app.get("/webhooks/manage", async (req, res) => {
  // Authenticate your user first
  const customer = await getCustomer(req.user.id);

  // Create a portal session
  const session = await createPortalSession(customer.nahookAppId, {
    expiresInMinutes: 60,
    metadata: {
      userId: customer.id,
      email: customer.email,
    },
  });

  // Redirect to the portal
  res.redirect(session.portalUrl);
});

The one-time code expires in 5 minutes. Generate the portal session just before redirecting — don't pre-generate codes.

Session Parameters

Parameter	Default	Range	Description
`role`	`editor`	`admin`, `editor`, `viewer`	Controls what the customer can do (see permissions)
`expiresInMinutes`	60	1–60	How long the portal session lasts
`metadata`	`{}`	Max 10 keys	Attached to endpoints created during the session

Metadata keys: max 50 characters. Metadata values: max 500 characters.

What Your Customers Can Do

What a customer can do depends on the role you assign when creating the session. By default (editor), customers can:

Create and update webhook endpoints (webhook and Slack types)
Subscribe endpoints to event types you've defined
View delivery history and attempt details

With admin, they can additionally delete endpoints. With viewer, they get read-only access.

They cannot access other applications' endpoints, your workspace settings, billing, or API keys.

See the full permissions reference for details.