# BookedUp developers: API keys, webhooks & Zapier

> Send BookedUp leads, calls and bookings to your own systems with signed webhooks, and create or look up leads with an API key. AI assistants: see the MCP server docs instead.

- AI assistants (MCP + OAuth): https://getbookedup.ai/developers/ai-assistants and https://getbookedup.ai/developers/mcp
- OpenAPI 3.1: https://getbookedup.ai/openapi.json

## Overview

- **Webhooks** (push): BookedUp sends an HTTPS POST to your URL for the events you choose. Set them up under Settings > Integrations > Webhooks.
- **API keys** (pull and actions): check a key, subscribe a URL to events, fetch sample payloads, create a lead, or find a lead by phone number.

Everything is scoped to one business. Spam calls are never sent.

## API keys

Create a key in Settings > Integrations > API keys. Keys look like `bk_live_…` (43 random characters after the prefix) and are shown once; only a hash is stored. Up to 10 active keys per business. Send it as `Authorization: Bearer bk_live_...` or `X-API-Key: bk_live_...`. Revoking takes effect immediately and deletes Zapier subscriptions made with that key.

```bash
curl https://getbookedup.ai/api/integrations/zapier/me -H "Authorization: Bearer $BOOKEDUP_API_KEY"
```

## Webhooks

Add a public `https://` endpoint (no private or internal addresses), a name and events. The signing secret (`whsec_…`) is shown once and can be rotated. Up to 10 endpoints per business. Every delivery is a JSON `POST` with headers `BookedUp-Signature`, `BookedUp-Event-Id` and `BookedUp-Event-Type`.

Envelope (version `2026-11-11`, additive changes only):

```json
{
  "id": "evt_00000000000000000000000000000001",
  "type": "lead.created",
  "created_at": "2026-11-12T15:00:00.000Z",
  "api_version": "2026-11-11",
  "data": {
    "lead_id": "00000000-0000-4000-8000-000000000001",
    "business": {
      "id": "00000000-0000-4000-8000-0000000000aa",
      "name": "Acme Plumbing"
    },
    "source": "phone",
    "name": "Jane Sample",
    "phone": "+16155550123",
    "address": "123 Main St, Nashville, TN 37203",
    "within_service_area": true,
    "issue": "AC is blowing warm air",
    "urgency": "soon",
    "status": "completed",
    "outcome": "callback_requested",
    "preferred_time": "Tomorrow morning",
    "appointment": null,
    "summary": "Sample lead from BookedUp. Caller needs AC service.",
    "duration_seconds": 142,
    "recording_available": true,
    "tags": [],
    "custom_answers": {},
    "lead_url": "https://getbookedup.ai/dashboard/leads/00000000-0000-4000-8000-000000000001",
    "created_at": "2026-11-11T15:04:05.000Z",
    "updated_at": null
  }
}
```

- Fields a business turned off (email, address, issue) are left out, not sent as null.
- Times are ISO-8601 UTC; appointments also carry the business's IANA `timezone`.
- Recordings and transcripts are never included: use `lead_url` (dashboard login required).
- Lead `source` is `phone`, `booking_page` or `manual` (added by hand, in the dashboard or with `POST /leads`). A hand-added lead has `status` `manual` and, until set, `outcome` `lead`.
- Real event ids are `evt_` plus 32 hex characters. Test events and `GET /samples/:event` samples have ids starting with `evt_test_` and carry `"test": true`; real events never do.

## Verifying signatures

`BookedUp-Signature` is `t=<unix seconds>,v1=<hex>`: HMAC-SHA256 of `<t>.<raw body>` keyed with your whole secret (including `whsec_`). Use the raw body, compare in constant time, accept any `v1`, and reject timestamps more than 5 minutes off.

```javascript
const crypto = require("node:crypto");

// rawBody: the request body exactly as received (string or Buffer), before JSON.parse.
function verifyBookedUp(rawBody, header, secret, toleranceSec = 300) {
  if (!header) return false;
  const parts = Object.create(null);
  const sigs = [];
  for (const piece of header.split(",")) {
    const [k, v] = piece.trim().split("=", 2);
    if (k === "t") parts.t = v;
    else if (k === "v1" && v) sigs.push(v);
  }
  if (!/^\d+$/.test(parts.t || "") || !sigs.length) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t)) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest();
  return sigs.some((s) => {
    if (!/^[0-9a-f]{64}$/i.test(s)) return false;
    const got = Buffer.from(s, "hex");
    return got.length === expected.length && crypto.timingSafeEqual(got, expected);
  });
}

// Express example: keep the raw body for verification.
// app.post("/webhooks/bookedup", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verifyBookedUp(req.body, req.get("BookedUp-Signature"), process.env.BOOKEDUP_WEBHOOK_SECRET)) return res.sendStatus(400);
//   const event = JSON.parse(req.body.toString("utf8"));
//   res.sendStatus(200); // reply fast, then process event (dedupe on event.id)
// });

```

```python
import hashlib
import hmac
import time


def verify_bookedup(raw_body: bytes, header: str, secret: str, tolerance_sec: int = 300) -> bool:
    """raw_body: the request body bytes exactly as received, before json.loads."""
    if not header:
        return False
    t, sigs = None, []
    for piece in header.split(","):
        k, _, v = piece.strip().partition("=")
        if k == "t" and v.isdigit():
            t = v
        elif k == "v1" and v:
            sigs.append(v)
    if t is None or not sigs:
        return False
    if abs(int(time.time()) - int(t)) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s.lower()) for s in sigs)


# Flask example:
# @app.post("/webhooks/bookedup")
# def bookedup():
#     if not verify_bookedup(request.get_data(), request.headers.get("BookedUp-Signature"), SECRET):
#         abort(400)
#     event = request.get_json()
#     return "", 200

```

```php
<?php
// $rawBody must be the body exactly as received, before json_decode():
// $rawBody = file_get_contents('php://input');
// $header  = $_SERVER['HTTP_BOOKEDUP_SIGNATURE'] ?? null;
function verify_bookedup(string $rawBody, ?string $header, string $secret, int $toleranceSec = 300): bool {
    if (!$header) return false;
    $t = null;
    $sigs = [];
    foreach (explode(',', $header) as $piece) {
        $kv = explode('=', trim($piece), 2);
        if (count($kv) !== 2) continue;
        [$k, $v] = $kv;
        if ($k === 't' && ctype_digit($v)) $t = $v;
        elseif ($k === 'v1' && $v !== '') $sigs[] = strtolower($v);
    }
    if ($t === null || !$sigs) return false;
    if (abs(time() - (int) $t) > $toleranceSec) return false;
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($sigs as $s) {
        if (hash_equals($expected, $s)) return true;
    }
    return false;
}

```

## Delivery & retries

- Reply 2xx within 10 seconds. Redirects are not followed. We read at most 4 KB of your response.
- Up to 8 attempts over about a day: now, 1 min, 5 min, 30 min, 2 h, 5 h, 8 h, 8 h (±10% jitter).
- 15 failures in a row spanning at least 12 hours turns the endpoint off and emails the business.
- Deliveries can repeat or arrive out of order: dedupe on the event `id`. Replying 410 removes a Zapier-style subscription.

## Event reference

### lead.created

A call (or booking-page request) ended with a real lead. Spam is never sent.

### lead.updated

You edited a lead in the dashboard.

### call.completed

Any call that was not spam ended (including hang-ups and voicemails).

### booking.created

An appointment was booked on your calendar (phone or booking page).

### booking.rescheduled

A customer moved their appointment.

### booking.cancelled

A customer cancelled their appointment.

## API endpoints

Base URL `https://getbookedup.ai/api/integrations/zapier`. All endpoints need an API key. JSON bodies.

- `GET /me`: check a key; returns the business.
- `POST /subscribe` `{ target_url, event }`: subscribe an HTTPS URL to one event (up to 50). Returns `id`.
- `DELETE /unsubscribe` (`{ id }` or `?id=`): remove a subscription. Safe to repeat.
- `GET /samples/:event`: up to 3 recent payloads of that event, or a sample (`"test": true`, id `evt_test_…`).
- `POST /leads`: create a lead. Required `name`, `phone`; optional `email`, `address`, `service_needed`, `notes`, `urgency` (`emergency`, `soon`, `standard`, `flexible`). Returns the lead with `source` `manual`; `service_needed` comes back as `issue`, `notes` as `summary`. Errors name the field you sent.
- `GET /leads/search?phone=`: newest lead for a 10-digit US number (zero or one item).

## Errors & limits

`400` invalid input or `Invalid JSON body`; `401` `Missing API key` (no key header) or `Invalid API key` (malformed or revoked); `404` not found; `413` body over 32 KB; `429` more than 120 requests a minute per key. Every keyed response has `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds); a 429 also has `Retry-After`.

## Zapier

A native Zapier app is on the roadmap. Today use Webhooks by Zapier (Catch Hook) as a webhook endpoint.