Getting Started

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your App      │────▶│    Hookbase     │────▶│  Customer's     │
│   (Backend)     │     │      API        │     │   Endpoint      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │
        │                       │
        ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│   Your App      │     │   Hookbase      │
│   (Frontend)    │────▶│    Portal       │
└─────────────────┘     └─────────────────┘

npm install @hookbase/sdk

import { Hookbase } from '@hookbase/sdk';
 
const hookbase = new Hookbase({
  apiKey: process.env.HOOKBASE_API_KEY,
});

// When a new customer signs up
const app = await hookbase.applications.create({
  name: customer.name,
  uid: customer.id, // Your internal customer ID
  metadata: {
    plan: customer.plan,
    email: customer.email,
  },
});

// Set up the event types your customers can subscribe to
await hookbase.eventTypes.create({
  name: 'order.created',
  displayName: 'Order Created',
  description: 'Triggered when a new order is placed',
  category: 'Orders',
});
 
await hookbase.eventTypes.create({
  name: 'order.shipped',
  displayName: 'Order Shipped',
  description: 'Triggered when an order ships',
  category: 'Orders',
});
 
await hookbase.eventTypes.create({
  name: 'payment.completed',
  displayName: 'Payment Completed',
  description: 'Triggered when payment is received',
  category: 'Payments',
});

// When an event occurs in your application
await hookbase.messages.send(customer.hookbaseAppId, {
  eventType: 'order.created',
  payload: {
    orderId: order.id,
    amount: order.total,
    currency: order.currency,
    items: order.items,
    customer: {
      id: order.customerId,
      email: order.customerEmail,
    },
  },
  eventId: `order_created_${order.id}`, // For deduplication
});

npm install @hookbase/portal

// Backend API endpoint
app.get('/api/webhook-portal-token', async (req, res) => {
  const customer = await getCustomerFromSession(req);
 
  const token = await hookbase.portalTokens.create(customer.hookbaseAppId, {
    expiresIn: 3600, // 1 hour
  });
 
  res.json({ token: token.token });
});

import { useState, useEffect } from 'react';
import {
  HookbasePortal,
  EndpointList,
  EndpointForm,
  SubscriptionManager,
  MessageLog,
} from '@hookbase/portal';
import '@hookbase/portal/styles.css';
 
function WebhookSettings() {
  const [portalToken, setPortalToken] = useState<string | null>(null);
  const [selectedEndpoint, setSelectedEndpoint] = useState(null);
 
  useEffect(() => {
    fetch('/api/webhook-portal-token')
      .then((res) => res.json())
      .then((data) => setPortalToken(data.token));
  }, []);
 
  if (!portalToken) return <div>Loading...</div>;
 
  return (
    <HookbasePortal token={portalToken}>
      <div className="grid grid-cols-2 gap-6">
        <div>
          <h2 className="text-xl font-semibold mb-4">Endpoints</h2>
          <EndpointForm
            onSuccess={(endpoint, secret) => {
              // Show the secret to the user - it won't be available again
              alert(`Save this secret: ${secret}`);
            }}
          />
          <EndpointList
            onEndpointClick={setSelectedEndpoint}
          />
        </div>
 
        <div>
          {selectedEndpoint ? (
            <>
              <h2 className="text-xl font-semibold mb-4">Subscriptions</h2>
              <SubscriptionManager endpointId={selectedEndpoint.id} />
            </>
          ) : (
            <p>Select an endpoint to manage subscriptions</p>
          )}
        </div>
      </div>
 
      <div className="mt-8">
        <h2 className="text-xl font-semibold mb-4">Delivery History</h2>
        <MessageLog
          limit={25}
          refreshInterval={30000}
        />
      </div>
    </HookbasePortal>
  );
}

import { createWebhook } from '@hookbase/sdk';
 
// Create a verifier with the endpoint's signing secret
const webhook = createWebhook(process.env.WEBHOOK_SECRET);
 
// Express.js example
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const payload = webhook.verify(req.body.toString(), req.headers);
 
    // Process the webhook
    switch (payload.type) {
      case 'order.created':
        handleOrderCreated(payload.data);
        break;
      case 'payment.completed':
        handlePaymentCompleted(payload.data);
        break;
    }
 
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(401).send('Invalid signature');
  }
});

await hookbase.messages.send(appId, {
  eventType: 'order.created',
  payload: orderData,
  eventId: `order_created_${order.id}`,
});

// Store the Hookbase app ID in your database
const app = await hookbase.applications.getOrCreate(customer.id, {
  name: customer.name,
});
 
// Later, use the UID to find the app
const app = await hookbase.applications.getByUid(customer.id);

// List failed messages
const { data: failures } = await hookbase.messages.listAllOutbound(appId, {
  status: 'exhausted',
});
 
// Notify customer about failures
for (const failure of failures) {
  await notifyCustomer(appId, {
    message: `Webhook delivery failed to ${failure.endpointUrl}`,
    eventType: failure.eventType,
    error: failure.lastError,
  });
}

// Retry a specific failed delivery
await hookbase.messages.retry(appId, outboundMessageId);
 
// Resend to all endpoints
await hookbase.messages.resend(appId, messageId);

await hookbase.eventTypes.create({
  name: 'order.created',
  category: 'Orders',
});
 
await hookbase.eventTypes.create({
  name: 'order.shipped',
  category: 'Orders',
});
 
await hookbase.eventTypes.create({
  name: 'invoice.created',
  category: 'Billing',
});

{
  "type": "order.created",
  "data": {
    "orderId": "ord_123",
    "amount": 99.99,
    "currency": "USD"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "webhookId": "msg_abc123"
}