How to set up TBBN webhooks

A webhook is a URL on your server that TBBN calls the moment something happens — an offer is accepted, a trade completes, a Space booking is paid. Use it to keep your own system in sync without polling the API.

There are two kinds:

Webhook	Events	Set up on
Merchant webhooks	Trade Engine events: offers, checkout, trades	merchants.tbbnetwork.com → Webhooks
Business webhooks	Space booking events	business.tbbnetwork.com → your Business → Webhooks

Before you start

You need an HTTPS URL on your server that:

• accepts POST requests with a JSON body,
• answers with any 2xx status within a few seconds (do slow work afterwards),
• checks the signature on every request (below).

Add a Merchant webhook

1. Sign in at merchants.tbbnetwork.com and select Webhooks.
2. Enter your endpoint's URL, for example https://yourapp.com/webhooks/tbbn.
3. Select Add endpoint. It's subscribed to offer.accepted, checkout.started and trade.completed.
4. The endpoint appears in the table with its Signing secret (whsec_…). Store it on your server.

The full list of events, and how to subscribe to others through the API, is in Webhooks & events.

Add a Business webhook (Space bookings)

You need the Admin or Developer role on the Business.

1. Go to business.tbbnetwork.com and open your Business.
2. Under Webhooks, enter your endpoint's URL.
3. Choose events: Everything, or any of Booking created, Booking paid, Booking completed, Booking cancelled and Booking no-show.
4. Select Add webhook. Copy its Signing secret.

Check every delivery is really from TBBN

Each request has a header:

X-TBBN-Signature: t=1767225600,v1=5f2c…

To verify it:

1. Read t (a Unix timestamp) and v1 (a hex signature) from the header.
2. Compute an HMAC-SHA256 of t, a dot, and the raw request body — ${t}.${rawBody} — using your endpoint's signing secret.
3. Compare it with v1 using a constant-time comparison.
4. Reject the request if they don't match, or if t is more than 5 minutes old.

Every TBBN SDK includes verifyWebhookSignature(), which does all of this — see SDKs.

If your endpoint is down

TBBN retries: three quick attempts, then after 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours. After that the delivery is set aside so you can replay it. The same event can arrive more than once — use its deliveryId to ignore duplicates. Details are in Webhooks & events.

Turn a webhook off

Select Disable next to it. TBBN stops sending to it immediately.

Common questions

I'm not receiving anything. Check the URL is public HTTPS (not localhost) and returns 2xx. For local testing, use a tunnelling tool that gives your machine a public URL.

Signatures never match. Make sure you sign the raw body exactly as received — not re-encoded JSON — and that you're using the secret for that specific endpoint.

Do webhooks use my API key? No. Each endpoint has its own signing secret.