Build on Tatbiq

1. In your dashboard, open Settings → API and webhooks and generate an API key. Copy it straight away: it is shown once.
2. Call the API from your server with that key. Every endpoint lives under:

https://www.tatbiq.store/api/v1

Try it with your own key:

curl https://www.tatbiq.store/api/v1/business \
  -H "Authorization: Bearer tk_your_key_here"

API access is part of your plan. If your plan doesn't include it, calls answer 402 with the code plan_required.

Send your key in the Authorization header on every request: Authorization: Bearer tk_.... A key can do everything the endpoints below allow for your business, so keep it on your server. Never put it in a website, an app download or a public repository.

If a key leaks, revoke it in the dashboard and make a new one. A revoked key stops working at once. The dashboard also shows when each key was last used.

Requests and responses are JSON. Times are ISO 8601 in UTC. Money is a number in your business's currency.

Every error has the same shape, with a status code that matches:

{ "error": { "code": "not_found", "message": "No such booking" } }

400 invalid_request

Something in the query or body is wrong. details lists each field's problem.

401 unauthorized

The key is missing, mistyped or revoked.

402 plan_required

Your plan doesn't include API access.

403 forbidden

The business account is suspended.

404 not_found

No such record in your business.

409 conflict

The change clashes with something, e.g. the new time is taken.

429 rate_limited

Too many requests. Wait for the Retry-After header's seconds.

Rate limit: 120 requests a minute per key.

Paging: lists return the newest first, 50 at a time (up to 100 with ?limit=). When there is more, the response has a nextCursor; pass it back as ?cursor= for the next page. When nextCursor is null, you have everything.

Instead of asking the API over and over, let us tell you. In Settings → API and webhooks, add an endpoint: an https address on your server. Choose all events or just some. Whenever one happens, we send it a POST with a JSON body.

Booking events carry the same booking object as the API, in data.booking. customer.created carries data.customer. The Send test button sends a ping event.

POST /webhooks/tatbiq HTTP/1.1
Content-Type: application/json
User-Agent: Tatbiq-Webhooks/1.0
Tatbiq-Event: booking.cancelled
Tatbiq-Delivery: cmh3...
Tatbiq-Signature: t=1760090000,v1=5f2b...

{ "id": "evt_8c1f...", "type": "booking.cancelled", "createdAt": "2026-10-10T09:30:00.000Z", "data": { "booking": { ... } } }

Answer with any 2xx status within 10 seconds. Do slow work after you answer. Anything else counts as a failure and is retried. We don't follow redirects.

Each endpoint has its own signing secret (whsec_...), shown when you add it and again under Show secret. The Tatbiq-Signature header is t=<unix seconds>,v1=<hex>, where the hex is an HMAC SHA-256 of <t>.<raw body> using that secret. Check it on every request, and refuse ones older than 5 minutes so a copied request can't be replayed later.

Node.js

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.TATBIQ_WEBHOOK_SECRET; // whsec_...

// Read the raw body: the signature is over the exact bytes we sent.
app.post("/webhooks/tatbiq", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Tatbiq-Signature") ?? "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");

  const fresh = Math.abs(Date.now() / 1000 - t) < 300;
  const valid =
    parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!fresh || !valid) return res.status(400).send("bad signature");

  const event = JSON.parse(req.body);
  // Skip events you've already handled: the same event can arrive more than once.
  console.log(event.id, event.type, event.data);
  res.sendStatus(200);
});

Python

import hashlib, hmac, json, time

def verify(secret: str, raw_body: bytes, header: str) -> dict:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts["t"])
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    if abs(time.time() - t) > 300 or not hmac.compare_digest(expected, parts.get("v1", "")):
        raise ValueError("bad signature")
    return json.loads(raw_body)

Need a new secret? New secret replaces it immediately, so update your server right after.

If a delivery fails, we try again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h: 8 tries over about two days. After that it is marked failed, and you can send it again from the delivery log in your dashboard. Each event has an id that stays the same across retries and resends. Store the ids you have handled and skip repeats, because the same event can arrive more than once.

Events are sent in the order they happen, but a retry can arrive after a later event. Use the booking's updatedAt to keep the newest version, or fetch the booking from the API when an event arrives.

Turning an endpoint off stops new events and drops any retries still waiting. Delivery history is kept for 30 days.