# Blinkerbot booking connection > Blinkerbot is an AI assistant (WhatsApp, Instagram, Messenger, web chat, phone) for businesses. When a business keeps its bookings in its own system, Blinkerbot calls ONE signed HTTPS endpoint on that system to read free slots and create real bookings. This file is the complete contract for implementing that endpoint. Contract version: 1. Machine-readable: openapi.yaml (OpenAPI 3.1, webhook `bookingContract`). Ready-made: single-file PHP package `blinkerbot-booking.php` (PHP 7.4+, no Composer), Node (Express) and Python (FastAPI) examples. The developer only writes four functions: listServices, findSlots, createBooking, cancelBooking (+ optional getBooking). ## Request - `POST {endpoint_url}` (https, port 443), `Content-Type: application/json`. Every operation goes to the same URL. - Body: `{"operation": "...", "request_id": "req_...", "idempotency_key": "..." | null, "account": null | "...", "test": false, "data": {...}}` - `account` is only used when one endpoint serves several businesses; usually null. - Times: ISO 8601 with UTC offset (`2026-11-20T14:00:00+03:00`), plus `timezone` (IANA, e.g. `Europe/Istanbul`). ## Signature (Standard Webhooks v1) - verify BEFORE parsing JSON - Headers: `webhook-id`, `webhook-timestamp` (Unix seconds), `webhook-signature` (`v1,`; several space-separated values while a secret rotates; accept if ANY matches). - Key: base64-decode the part of the secret after `whsec_`. - Signed content: `{webhook-id}.{webhook-timestamp}.{raw request body bytes}` with HMAC-SHA256, base64 encoded. - Reject (HTTP 401) when the timestamp is more than 300 seconds from now or no signature matches. Compare in constant time (hash_equals / crypto.timingSafeEqual / hmac.compare_digest). - Read the raw body exactly as received (PHP: `php://input`; Express: `express.raw`; FastAPI: `await request.body()`). Never re-serialize before verifying. - Libraries: `npm install standardwebhooks`, `pip install standardwebhooks`, `composer require standard-webhooks/standard-webhooks`. Test vector: secret `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`, id `msg_p5jXN8AQM9LWM0D4loKWxJek`, timestamp `1614265330`, body `{"test": 2432232314}` -> `v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=`. ## Operations - `ping` - data `{}` -> `{"pong": true, "capabilities": ["replaces_booking_id"]}` (any object is fine). Required. List `replaces_booking_id` in `capabilities` only when create_booking handles it in one transaction (see Time change); the ready-made packages do. - `list_services` - data `{}` -> `{"services": [{"id": "svc_1", "name": "Haircut", "duration_minutes": 30, "price": 500, "staff": [{"id": "st_1", "name": "Ayse"}]}]}`. `price` and `staff` optional. Required. - `find_slots` - data `{"service_id", "staff_id"?, "from", "to", "timezone", "limit"?}` -> `{"slots": [{"start", "end", "staff_id"?}]}` free slots in the range (only that staff member when `staff_id` is given), sorted by start, at most `limit` of them (integer 1-500; absent -> 500; anything else -> HTTP 400). The panel test sends `limit: 50`. Keep the whole answer under 65536 bytes (one slot is ~90 bytes). Required. - `create_booking` - `idempotency_key` required; data `{"service_id", "staff_id"?, "start", "end", "timezone", "customer": {"name", "phone", "email"?}, "channel", "note"?, "replaces_booking_id"?}` -> `{"booking_id", "status": "confirmed" | "pending", "start", "end", "staff_id"?, "replaced"?}`. Required. - `get_booking` - data `{"booking_id"}` -> `{"booking_id", "status": "confirmed" | "pending" | "cancelled", "start", "end", "staff_id"?}`. Recommended. - `cancel_booking` - data `{"booking_id"}` -> `{"booking_id", "status": "cancelled"}`. Repeating it must succeed again. Recommended. - Not implemented (e.g. no get_booking) / unknown operation -> HTTP 200 `{"ok": false, "error": {"code": "not_implemented"}}`. NEVER a 5xx (501 included): every 5xx means "unreachable" (retries, circuit breaker, failed panel test). `not_implemented` is not a business code; Blinkerbot treats it as "not supported here". ## Answers - Success: HTTP 200 `{"ok": true, "data": {...}}`. - Business error: HTTP 200 `{"ok": false, "error": {"code": "", "message": ""}}`. - Business codes (exactly these): `slot_unavailable`, `invalid_service`, `invalid_staff`, `outside_hours`, `invalid_customer`, `booking_not_found`, `cancellation_not_allowed`, `idempotency_mismatch`, `request_in_progress`. - Bad signature: HTTP 401. Malformed signed request: HTTP 400. - Always JSON with `Content-Type: application/json` and `Cache-Control: no-store`. Never an HTML page, never a redirect. Do not leak stack traces or secrets. - Blinkerbot treats timeouts, 5xx (501 included), 429, HTML/non-JSON and `request_in_progress` as "unreachable" (keeps the request pending, retries with the same key); other status codes, `not_implemented` and unknown codes as permanent errors. Answers over 65536 bytes are refused (permanent error). `message` is never shown to the assistant or the customer. ## Idempotency (create_booking, cancel_booking) - Same key + same content -> return the FIRST answer, create nothing new. - Same key + different content -> `idempotency_mismatch`. Content = SHA-256 of canonical JSON (sorted keys, no whitespace) of `{"data": ..., "operation": ...}`. - Same key while the first request is still running -> wait briefly and return the same answer, or answer `request_in_progress`. - Store the key in the SAME database transaction as the booking (unique column). Keep keys at least 7 days. Scope keys by test/live, account and operation. Business errors need not be stored (the ready-made packages roll them back, so a retry with the same key runs again). ## Test mode - `test: true` -> run the operation completely, then roll the transaction back. No booking may remain. Keeping the idempotency answer of a test request is allowed so that a repeated test request returns the same `booking_id`. ## Time change - `create_booking` with `replaces_booking_id`: cancel the old booking and create the new one in ONE transaction (cancel first, so the new time may overlap the old one), answer `replaced: true`. If the new booking fails, the old one stays. Advertise it with `ping` -> `"capabilities": ["replaces_booking_id"]`; without that Blinkerbot creates the new booking first and cancels the old one afterwards, which fails with `slot_unavailable` when the two times overlap for the same staff. ## Pairing (setup) - The owner creates a code `blk_pair_` + 26 base32 characters in the Blinkerbot panel (2 hours, single use). - Your package/CLI sends `POST https://api.blinkerbot.com/public/v1/pair` with `{"code", "endpoint_url", "package_kind": "php" | "node" | "python" | "custom", "package_version", "account"?}`. - Success: `{"ok": true, "data": {"signing_secret": "whsec_...", "workspace_name": "...", "contract_version": 1}}`. Failure (always the same): HTTP 400 `{"ok": false, "error": {"code": "pairing_failed"}}`. - Save the secret to a private file (mode 0600, outside the web root) or an environment variable. Never print, log, email or commit it. ## Time limits - Phone: find_slots 2.5 s, create/cancel/get 3.5 s. Chat: find_slots 5 s, create/cancel/get 8 s. ping/list_services 5 s. ## Automatic test in the panel (must be green before the connection can be switched on) 1 ping; 2 three bad requests (wrong signature, 10-minute-old timestamp, other secret) all get 401, then a good ping gets 200; 3 list_services; 4 find_slots for the first service, next 7 days, `limit: 50`; 5 create_booking with test:true; 6 same key -> same booking_id; 7 same key, other content -> idempotency_mismatch; 8 get/cancel if implemented (`not_implemented` at HTTP 200 = skipped, a 5xx = fail); 9 each step under the phone limit (warning only). ## Troubleshooting - 403 on every request: Cloudflare Bot Fight Mode / WAF or a security plugin (Wordfence, ModSecurity) blocks it - add a rule for this URL. - 401: wrong secret, server clock off (use NTP), or a proxy/framework re-encodes the body. PHP package paired from the command line: the web server user (www-data, nobody) must be able to read the 0600 secret file - run the pair command as that user (`sudo -u www-data php endpoint.php pair ...`) or use the setup screen. - HTML with 200: a maintenance/login/404 page answers instead of the endpoint. - Stale answers: a cache plugin caches the URL - exclude it. - Times off by hours: return offsets (`+03:00`), not naive times. - Local development: expose your port with `cloudflared tunnel --url http://localhost:8080` or `ngrok http 8080`.