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:
- npm package (
@hookbase/portal) — React components and hooks you drop into your frontend - Hosted page — a ready-made page at
hookbase.app/portal/{token}you can link to or iframe
Installation (npm)
npm install @hookbase/portalPeer 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 has the same features as the npm package. On Starter plans and above it can carry your logo, colours and support links, be shown in six languages, and (Pro and above) run on your own domain. See Branding, Languages and Custom Domains. For full control over layout, use the npm package instead.
What Your Customers Can Do
| Feature | Description |
|---|---|
| Manage endpoints | Create, edit, disable, and delete webhook URLs |
| Subscribe to events | Choose which event types each endpoint receives |
| Browse event types | See every event type with its schema, example payload and docs link |
| View delivery history | See message status, attempts, the delivered payload, and each endpoint response |
| Send test events | Fire a test webhook to verify endpoint connectivity |
| Replay failed messages | Retry individual messages or bulk-replay all failures |
| Verify endpoints | Confirm endpoint ownership via challenge/response |
| Rotate secrets | Generate new signing secrets with a grace period of up to 24 hours |
| Tune delivery | Set success status codes, retry backoff and custom retry delays per endpoint |
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
- Magic Links — Generate short-lived portal URLs
- Components — All available React components
- Hooks — Data hooks for headless/custom UIs
- Styling — Theme customization and CSS variables
- Branding & Domains — Hosted-portal branding, languages and custom domains
- Portal API Reference — REST API endpoints