Hookbase

Portal Overview

The Hookbase Portal lets your customers manage their own webhook endpoints directly inside your application. There are two ways to embed the portal:

  1. npm package (@hookbase/portal) — React components and hooks you drop into your frontend
  2. Hosted page — a ready-made page at hookbase.app/portal/{token} you can link to or iframe

Installation (npm)

npm install @hookbase/portal

Peer dependencies: react >= 18, react-dom >= 18.

Quick Start

import { HookbasePortal, EndpointList, EndpointForm } from '@hookbase/portal';
import '@hookbase/portal/styles.css';
 
function WebhookSettings({ portalToken }: { portalToken: string }) {
  return (
    <HookbasePortal token={portalToken}>
      <EndpointForm />
      <EndpointList />
    </HookbasePortal>
  );
}

Getting a Portal Token

Generate tokens server-side via the Hookbase API. Tokens use the whpt_ prefix and authenticate all portal requests.

// Your backend
app.get('/api/webhook-portal-token', async (req, res) => {
  const customer = await getCustomerFromSession(req);
 
  const response = await fetch(
    `https://api.hookbase.app/api/organizations/${ORG_ID}/portal/webhook-applications/${customer.appId}/tokens`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${API_KEY}`,
      },
      body: JSON.stringify({
        scopes: ['read', 'write'],
        expiresInDays: 30,
      }),
    }
  );
 
  const { data } = await response.json();
  res.json({ token: data.token });
});

See Magic Links for short-lived session tokens and hosted portal URLs.

Hosted Portal

Every Hookbase organization gets a hosted portal page. Generate a magic link and redirect your customer or embed it in an iframe:

<iframe
  src="https://www.hookbase.app/portal/whpt_abc123..."
  width="100%"
  height="600"
  frameborder="0"
></iframe>

The hosted page renders the same components as the npm package with default styling. For full control over appearance, use the npm package instead.

What Your Customers Can Do

FeatureDescription
Manage endpointsCreate, edit, disable, and delete webhook URLs
Subscribe to eventsChoose which event types each endpoint receives
View delivery historySee message status, attempt count, and timestamps
Send test eventsFire a test webhook to verify endpoint connectivity
Replay failed messagesRetry individual messages or bulk-replay all failures
Verify endpointsConfirm endpoint ownership via challenge/response
Rotate secretsGenerate new signing secrets with a 24-hour grace period

Architecture

┌─────────────────────────────────────────┐
│  Your Application                       │
│  ┌────────────────────────────────────┐  │
│  │  <HookbasePortal token={...}>     │  │
│  │    <EndpointList />               │  │
│  │    <SubscriptionManager />        │  │
│  │    <MessageLog />                 │  │
│  └────────────────────────────────────┘  │
└─────────────────────────────────────────┘
          │ Portal Token (whpt_xxx)
          ▼
┌─────────────────────────────────────────┐
│  Hookbase API                           │
│  /portal/* endpoints                    │
│  Scoped to the customer's application   │
└─────────────────────────────────────────┘

All API calls are scoped to the application associated with the portal token. Customers cannot access other applications or organization-level resources.

Next Steps

PreviousSDK ReferenceNextMagic Links