Skip to content
Webhooks & Events

Every sign-up, payment and plan change, signed and posted to your server.

Pick from 239 events and point them at an HTTPS endpoint, and BuildBase POSTs a signed JSON body each time one fires. One SDK call verifies the signature and parses the event, and the console shows every delivery attempt.

Your app is an organization in BuildBase. Your users sign in and work inside workspaces - one per team or customer.

You set up

In the console and the SDK

  • The address on your server that receives events
  • Which events you want to hear about
  • One call on your server to check each event is really from us

You get

For you and your team

  • Sign-ups, payments and plan changes, sent to your server as they happen
  • Retries when your server is briefly down
  • A log of every delivery in the console

Events your backend can trust

Signed, retried and logged, so a missed payment or a new member reaches your system without you polling.

Choose Your Events

239 events - sign-ups, payments, plan changes, credits, workflows, enterprise SSO and more. Pick the ones you need, or all of them.

Signed So You Can Trust It

Every event is signed. One call on your server checks the signature and hands you the event.

Retried if You Miss It

If your server is down or errors, the event is sent again with growing gaps between tries.

Every Delivery Logged

See each attempt, its result and how long it took, in the console.

Details Included

Events carry the full workspace, user, subscription and plan, so you rarely need to look anything up.

Safe by Default

Only HTTPS addresses are accepted, and an address that keeps failing is paused until you turn it back on.

Verify and handle in one call

parseWebhookEvent() checks the signature and timestamp and returns { event, timestamp, data }, or null if anything is wrong. A retry carries the same event ID, so keep a note of the IDs you have handled and skip any repeat.

app/api/webhooks/route.tsTSX
import { parseWebhookEvent } from '@buildbase/sdk';

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

  // Verifies the signature and parses the payload - returns null on failure
  const parsed = parseWebhookEvent({
    body,
    signature: req.headers.get('x-buildbase-signature'),
    timestamp: req.headers.get('x-buildbase-timestamp'),
    secret: process.env.BUILDBASE_WEBHOOK_SECRET,
  });

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

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

  return Response.json({ received: true });
}
app/api/webhooks/dedupe/route.tsTSX
import { parseWebhookEvent } from '@buildbase/sdk';

export async function POST(req: Request) {
  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.BUILDBASE_WEBHOOK_SECRET!,
  });
  if (!event) return new Response('Invalid signature', { status: 401 });

  // The same evt_ id on every endpoint and on every retry
  const id = req.headers.get('x-buildbase-event-id');
  if (id && (await db.processedEvents.exists(id))) {
    return Response.json({ received: true });
  }

  await handle(event);
  if (id) await db.processedEvents.add(id);
  return Response.json({ received: true });
}

What every delivery carries

Built so your code can skip repeats, check each message with the library it already uses, and see why a delivery failed.

Handle each event once

Every event comes with its own ID, and the ID stays the same on every endpoint and every retry. Keep a note of the IDs you have handled and skip any repeat, so nothing runs twice when a delivery is retried.

Check it came from BuildBase

Every delivery is signed with your endpoint's secret, so you can prove it came from BuildBase and wasn't changed on the way. It is also signed the Standard Webhooks way, an open format many tools support, so any Standard Webhooks library can check it too.

Every attempt in the log

If a delivery fails, BuildBase tries again, waiting a little longer each time. Every attempt is logged with its result, how long it took and which try it was. A delivery shows as blocked when the address failed BuildBase's safety checks, and as throttled when your organization hit its sending limit.

A dead endpoint is switched off

If an endpoint keeps failing for over an hour, it's switched off and marked Auto-disabled. In production, your owners and admins get an email. Turn it back on and the count starts again from zero.

Secrets you can rotate

The signing secret is shown once. If it leaks, Rotate secret in the console gives you a new one, and the old one stops working straight away.

Separate while you test

Each development and staging environment has its own endpoints and signing secrets. While you build, they also accept plain http and tunnel addresses that reach your own computer. Production takes https only.

Frequently Asked Questions

What people ask about Webhooks.

Do my users see this?

No. Webhooks send events to your server so your backend can react.

Which events can I receive?

239, across users, workspaces, subscriptions, payments, credits, workflows, audience, email and more. Subscribe each endpoint to the ones it needs, or to all of them.

How do I know an event is really from you?

Every event is signed. parseWebhookEvent() checks the signature and the timestamp and gives you the event, or null if anything is wrong.

Can an event arrive twice or out of order?

Yes. A retry can send the same event again, and events can arrive in any order. Every event carries an ID, in its body and in a header, that stays the same on every endpoint and every retry, so skip any ID you have already handled. Delivery is best effort: each event gets 5 attempts over about 2.5 minutes, and one that fails all of them is not sent again.

Can I verify with a Standard Webhooks library?

Yes. Standard Webhooks is an open spec, with ready-made libraries that check a webhook really came from its sender. Every delivery also carries the headers those libraries read, signed with the same endpoint secret. The libraries want the secret in their whsec_ format, and the docs show the one line that converts it.

Can I send a test event or replay one?

No. There is no test or resend button - the delivery log shows every real attempt.

Send your first event to your own server

Add an endpoint in the console, copy the signing secret, and drop parseWebhookEvent() into a route. The next sign-up arrives signed.

Free plan7-day free trial on paid plansNo credit card required