Overview

BuildBase fires webhook events for every significant action - user signups, subscription changes, payments, credit usage, workspace updates, and more. Verify the signature and handle the event in your backend.

import { parseWebhookEvent } from '@buildbase/sdk';

export async function POST(req) {
  const body = await req.text();

  const event = parseWebhookEvent({
    body,
    signature: req.headers.get('x-buildbase-signature'),
    timestamp: req.headers.get('x-buildbase-timestamp'),
    secret: process.env.WEBHOOK_SECRET,
  });

  if (!event) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  switch (event.event) {
    case 'subscription.upgraded':
      await enablePremiumFeatures(event.data.workspaceId);
      break;
    case 'credit.low_balance':
      await notifyTeam(event.data.workspaceId);
      break;
    case 'workspace.member_added':
      await syncToExternalCRM(event.data);
      break;
  }

  return Response.json({ received: true });
}

Two functions

Use parseWebhookEvent for most cases. Use verifyWebhookSignature if you want to parse the body yourself.

Express / Hono example

import { parseWebhookEvent } from '@buildbase/sdk';

app.post('/webhooks', (req, res) => {
  const event = parseWebhookEvent({
    body: req.body,
    signature: req.headers['x-buildbase-signature'],
    timestamp: req.headers['x-buildbase-timestamp'],
    secret: process.env.WEBHOOK_SECRET,
  });

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

  // Handle event.event and event.data
  res.json({ received: true });
});

Event categories

86+ event types total. See the SDK README for the full list.

Event payload structure

Every webhook POST body has this shape - three fields, nothing else:

{
  "event": "subscription.upgraded",
  "timestamp": 1719000000,
  "data": {
    "workspaceId": "ws_xyz789",
    "userId": "usr_def456",
    "planId": "plan_starter",
    "planVersionId": "pv_v2",
    "billingInterval": "monthly",
    "previousPlanId": "plan_free"
  }
}

timestamp is Unix seconds, set when the event fires. Each delivery also carries three headers:

The data object varies by event type. Some common patterns:

Delivery guarantees

• At-least-once delivery - events may be delivered more than once. Deliveries carry no unique event ID; retries repeat the same event and timestamp, so deduplicate on a hash of the raw request body.
• No ordering guarantee - events may arrive out of order. Use event.timestamp if ordering matters.
• Automatic retries - a non-2xx response is retried 4 more times with exponential backoff, at roughly 10s, 20s, 40s and 80s, so the last attempt lands about 2.5 minutes after the first. A destination that is refused by our outbound safety checks is not retried at all; the delivery log says blocked.
• Signature expiry - signatures are valid for 5 minutes by default. Reject older payloads to prevent replay attacks.

Limits

Webhooks fan out: one event reaching ten endpoints is ten calls to your servers, and some events fire per recipient rather than per action. These bounds keep one busy hour from becoming a queue nobody can drain.

A throttled delivery never left BuildBase, so it is not a failure of your receiver and is not retried. email.sent fires once per recipient, so a large campaign is the usual way to meet the per-minute limit; subscribe an endpoint to the specific events you need rather than to * if that matters to you.

Re-enabling an auto-disabled endpoint from the console clears its failure count.

Next Steps

• Server SDK - Backend setup and all server methods.
• Billing - Subscription events and payment handling.