{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-getting-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab","cards","card"]},"type":"markdown"},"seo":{"title":"Webhook Guide","description":"Bookable is a TMS API gateway API — one integration to access real-time availability and manage bookings across venues on any table management system.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhook-guide","__idx":0},"children":["Webhook Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Bookable webhook system delivers real-time notifications to your endpoint when booking events occur — such as new bookings, updates, and cancellations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"integration-flow","__idx":1},"children":["Integration flow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Register"]}," your callback URL via the API and receive a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store"]}," the secret key securely — you'll use it to verify every incoming request"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement"]}," an HTTPS endpoint that accepts POST requests and verifies the HMAC-SHA256 signature"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respond"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}," on success"]}]},{"$$mdtype":"Tag","name":"Mermaid","attributes":{"data-language":"mermaid","diagramSource":"sequenceDiagram\n participant D as Your App\n participant BKB as Bookable\n participant WE as Your Webhook Endpoint\n\n Note over D,BKB: Phase 1: Registration\n D->>BKB: POST /webhooks {callbackUrl}\n BKB->>D: { secretKey }\n Note over D: Store secretKey securely\n\n Note over BKB,WE: Phase 2: Event Delivery\n loop For each booking event\n BKB->>BKB: Generate HMAC-SHA256 signature\n BKB->>WE: POST {callbackUrl}
X-API-Key: signature\n WE->>WE: Verify signature\n alt Valid\n WE->>BKB: 204 No Content\n else Invalid\n WE->>BKB: 401 Unauthorized\n end\n end\n\n Note over BKB,WE: Failed deliveries retry with exponential backoff\n","diagramHtml":""},"children":["sequenceDiagram\n participant D as Your App\n participant BKB as Bookable\n participant WE as Your Webhook Endpoint\n\n Note over D,BKB: Phase 1: Registration\n D->>BKB: POST /webhooks {callbackUrl}\n BKB->>D: { secretKey }\n Note over D: Store secretKey securely\n\n Note over BKB,WE: Phase 2: Event Delivery\n loop For each booking event\n BKB->>BKB: Generate HMAC-SHA256 signature\n BKB->>WE: POST {callbackUrl}
X-API-Key: signature\n WE->>WE: Verify signature\n alt Valid\n WE->>BKB: 204 No Content\n else Invalid\n WE->>BKB: 401 Unauthorized\n end\n end\n\n Note over BKB,WE: Failed deliveries retry with exponential backoff\n"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-register-your-webhook","__idx":2},"children":["Step 1: Register your webhook"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"obtain-an-access-token","__idx":3},"children":["Obtain an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/getting-started/auth"},"children":["Authentication"]}," for the full token flow. Quick reference:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://auth.bookabletech.com/oauth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"grant_type\": \"client_credentials\",\n \"client_id\": \"YOUR_CLIENT_ID\",\n \"client_secret\": \"YOUR_CLIENT_SECRET\",\n \"audience\": \"api.bookabletech.com\"\n }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"register-your-callback-url","__idx":4},"children":["Register your callback URL"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://api.bookabletech.com/webhooks \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"callbackUrl\": \"https://your-domain.com/webhooks/booking-notification\"\n }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch('https://api.bookabletech.com/webhooks', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${accessToken}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n callbackUrl: 'https://your-domain.com/webhooks/booking-notification',\n }),\n});\n\nconst { secretKey } = await response.json();\n// Store secretKey securely — you'll need it to verify incoming requests\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(\n 'https://api.bookabletech.com/webhooks',\n json={'callbackUrl': 'https://your-domain.com/webhooks/booking-notification'},\n headers={'Authorization': f'Bearer {access_token}'}\n)\nresponse.raise_for_status()\nsecret_key = response.json()['secretKey']\n# Store secret_key securely — you'll need it to verify incoming requests\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import java.net.http.*;\nimport java.net.URI;\n\nString body = \"\"\"\n { \"callbackUrl\": \"https://your-domain.com/webhooks/booking-notification\" }\n\"\"\";\n\nHttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.bookabletech.com/webhooks\"))\n .header(\"Authorization\", \"Bearer \" + accessToken)\n .header(\"Content-Type\", \"application/json\")\n .POST(HttpRequest.BodyPublishers.ofString(body))\n .build();\n\nHttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());\n// Parse response.body() to extract secretKey and store it securely\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"var payload = new { callbackUrl = \"https://your-domain.com/webhooks/booking-notification\" };\n\nvar response = await client.PostAsJsonAsync(\"https://api.bookabletech.com/webhooks\", payload);\nresponse.EnsureSuccessStatusCode();\n\nusing var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());\nvar secretKey = doc.RootElement.GetProperty(\"secretKey\").GetString();\n// Store secretKey securely — you'll need it to verify incoming requests\n","lang":"csharp"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"secretKey\": \"123e4567-e89b-12d3-a456-426655440000\",\n \"callbackUrl\": \"https://your-domain.com/webhooks/booking-notification\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Cards","attributes":{},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"⚠️ Store the secret key securely"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]}," is returned only once at registration. Store it in a secrets manager or environment variable — never hardcode it."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"update-your-callback-url","__idx":5},"children":["Update your callback URL"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT https://api.bookabletech.com/webhooks \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"callbackUrl\": \"https://your-new-domain.com/webhooks/booking-notification\"\n }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"await fetch('https://api.bookabletech.com/webhooks', {\n method: 'PUT',\n headers: {\n Authorization: `Bearer ${accessToken}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n callbackUrl: 'https://your-new-domain.com/webhooks/booking-notification',\n }),\n});\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"requests.put(\n 'https://api.bookabletech.com/webhooks',\n json={'callbackUrl': 'https://your-new-domain.com/webhooks/booking-notification'},\n headers={'Authorization': f'Bearer {access_token}'}\n).raise_for_status()\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"String updateBody = \"\"\"\n { \"callbackUrl\": \"https://your-new-domain.com/webhooks/booking-notification\" }\n\"\"\";\n\nHttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.bookabletech.com/webhooks\"))\n .header(\"Authorization\", \"Bearer \" + accessToken)\n .header(\"Content-Type\", \"application/json\")\n .PUT(HttpRequest.BodyPublishers.ofString(updateBody))\n .build();\n\nclient.send(request, HttpResponse.BodyHandlers.ofString());\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"var payload = new { callbackUrl = \"https://your-new-domain.com/webhooks/booking-notification\" };\nvar request = new HttpRequestMessage(HttpMethod.Put, \"https://api.bookabletech.com/webhooks\");\nrequest.Content = JsonContent.Create(payload);\n(await client.SendAsync(request)).EnsureSuccessStatusCode();\n","lang":"csharp"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"delete-your-webhook","__idx":6},"children":["Delete your webhook"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE https://api.bookabletech.com/webhooks \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"await fetch('https://api.bookabletech.com/webhooks', {\n method: 'DELETE',\n headers: { Authorization: `Bearer ${accessToken}` },\n});\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"requests.delete(\n 'https://api.bookabletech.com/webhooks',\n headers={'Authorization': f'Bearer {access_token}'}\n).raise_for_status()\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"HttpRequest request = HttpRequest.newBuilder()\n .uri(URI.create(\"https://api.bookabletech.com/webhooks\"))\n .header(\"Authorization\", \"Bearer \" + accessToken)\n .DELETE()\n .build();\n\nclient.send(request, HttpResponse.BodyHandlers.ofString());\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"(await client.DeleteAsync(\"https://api.bookabletech.com/webhooks\")).EnsureSuccessStatusCode();\n","lang":"csharp"},"children":[]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-implement-your-webhook-endpoint","__idx":7},"children":["Step 2: Implement your webhook endpoint"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint must accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests, verify the HMAC-SHA256 signature, process the event, and respond with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-event-types","__idx":8},"children":["Supported event types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking.created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new booking was created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking.updated"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An existing booking was modified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["booking.cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A booking was cancelled"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"full-endpoint-implementation","__idx":9},"children":["Full endpoint implementation"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"JavaScript","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"// Node.js / Express\nconst express = require('express');\nconst crypto = require('crypto');\n\nconst app = express();\napp.use(express.json());\n\nconst WEBHOOK_SECRET = process.env.BOOKABLE_WEBHOOK_SECRET;\n\napp.post('/webhooks/booking-notification', (req, res) => {\n try {\n if (!verifySignature(req.headers['x-api-key'], req.body, WEBHOOK_SECRET)) {\n return res.status(401).json({ success: false, error: 'unauthorized' });\n }\n\n const { eventType, timestamp, booking } = req.body;\n\n if (!eventType || !timestamp) {\n return res.status(400).json({ success: false, error: 'validation_error' });\n }\n\n switch (eventType) {\n case 'booking.created':\n case 'booking.updated':\n case 'booking.cancelled':\n console.log(`Event: ${eventType}, booking ID: ${booking[0]?.id}`);\n // Handle event...\n break;\n default:\n console.warn(`Unknown event type: ${eventType}`);\n }\n\n res.status(204).end();\n\n } catch (error) {\n console.error('Webhook error:', error);\n res.status(500).json({ success: false, error: 'internal_error' });\n }\n});\n\nfunction verifySignature(signature, body, secret) {\n if (!signature) return false;\n const expected = crypto\n .createHmac('sha256', secret)\n .update(JSON.stringify(body))\n .digest('hex');\n return crypto.timingSafeEqual(\n Buffer.from(signature, 'hex'),\n Buffer.from(expected, 'hex')\n );\n}\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"# Python / Flask\nfrom flask import Flask, request, jsonify\nimport hashlib\nimport hmac\nimport json\nimport os\n\napp = Flask(__name__)\n\nWEBHOOK_SECRET = os.environ['BOOKABLE_WEBHOOK_SECRET']\n\n@app.route('/webhooks/booking-notification', methods=['POST'])\ndef handle_booking_notification():\n try:\n if not verify_signature(request, WEBHOOK_SECRET):\n return jsonify({'success': False, 'error': 'unauthorized'}), 401\n\n data = request.get_json()\n event_type = data.get('eventType')\n timestamp = data.get('timestamp')\n booking = data.get('booking')\n\n if not event_type or not timestamp:\n return jsonify({'success': False, 'error': 'validation_error'}), 400\n\n if event_type in ('booking.created', 'booking.updated', 'booking.cancelled'):\n print(f\"Event: {event_type}, booking ID: {booking[0]['id'] if booking else 'unknown'}\")\n # Handle event...\n else:\n print(f\"Unknown event type: {event_type}\")\n\n return '', 204\n\n except Exception as e:\n print(f\"Webhook error: {e}\")\n return jsonify({'success': False, 'error': 'internal_error'}), 500\n\n\ndef verify_signature(req, secret):\n signature = req.headers.get('X-API-Key')\n if not signature:\n return False\n payload = json.dumps(req.get_json(), separators=(',', ':'))\n expected = hmac.new(\n secret.encode('utf-8'),\n payload.encode('utf-8'),\n hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(signature, expected)\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Java","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"// Spring Boot\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.bind.annotation.*;\nimport javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.util.HexFormat;\nimport java.util.Map;\n\n@RestController\npublic class WebhookController {\n\n private final String webhookSecret = System.getenv(\"BOOKABLE_WEBHOOK_SECRET\");\n\n @PostMapping(\"/webhooks/booking-notification\")\n public ResponseEntity handleWebhook(\n @RequestHeader(\"X-API-Key\") String signature,\n @RequestBody String rawBody,\n @RequestBody Map body) {\n\n if (!verifySignature(signature, rawBody, webhookSecret)) {\n return ResponseEntity.status(401).build();\n }\n\n String eventType = (String) body.get(\"eventType\");\n if (eventType == null) {\n return ResponseEntity.badRequest().build();\n }\n\n switch (eventType) {\n case \"booking.created\":\n case \"booking.updated\":\n case \"booking.cancelled\":\n System.out.println(\"Event: \" + eventType);\n // Handle event...\n break;\n default:\n System.out.println(\"Unknown event type: \" + eventType);\n }\n\n return ResponseEntity.noContent().build();\n }\n\n private boolean verifySignature(String signature, String payload, String secret) {\n try {\n Mac mac = Mac.getInstance(\"HmacSHA256\");\n mac.init(new SecretKeySpec(secret.getBytes(), \"HmacSHA256\"));\n String expected = HexFormat.of().formatHex(mac.doFinal(payload.getBytes()));\n return expected.equals(signature);\n } catch (Exception e) {\n return false;\n }\n }\n}\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"C#","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"// ASP.NET Core — minimal API\nusing System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\nvar builder = WebApplication.CreateBuilder(args);\nvar app = builder.Build();\n\nvar webhookSecret = Environment.GetEnvironmentVariable(\"BOOKABLE_WEBHOOK_SECRET\")!;\n\napp.MapPost(\"/webhooks/booking-notification\", async (HttpContext ctx) =>\n{\n ctx.Request.EnableBuffering();\n using var reader = new StreamReader(ctx.Request.Body, leaveOpen: true);\n var rawBody = await reader.ReadToEndAsync();\n ctx.Request.Body.Position = 0;\n\n var signature = ctx.Request.Headers[\"X-API-Key\"].ToString();\n if (!VerifySignature(signature, rawBody, webhookSecret))\n return Results.Unauthorized();\n\n using var doc = JsonDocument.Parse(rawBody);\n var eventType = doc.RootElement.GetProperty(\"eventType\").GetString();\n\n switch (eventType)\n {\n case \"booking.created\":\n case \"booking.updated\":\n case \"booking.cancelled\":\n Console.WriteLine($\"Event: {eventType}\");\n // Handle event...\n break;\n default:\n Console.WriteLine($\"Unknown event type: {eventType}\");\n break;\n }\n\n return Results.NoContent();\n});\n\nstatic bool VerifySignature(string signature, string payload, string secret)\n{\n var keyBytes = Encoding.UTF8.GetBytes(secret);\n var payloadBytes = Encoding.UTF8.GetBytes(payload);\n var expected = Convert.ToHexString(\n HMACSHA256.HashData(keyBytes, payloadBytes)\n ).ToLower();\n return CryptographicOperations.FixedTimeEquals(\n Encoding.UTF8.GetBytes(expected),\n Encoding.UTF8.GetBytes(signature)\n );\n}\n\napp.Run();\n","lang":"csharp"},"children":[]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-payload","__idx":10},"children":["Webhook payload"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n \"eventType\": \"booking.created\",\n \"timestamp\": \"2025-06-17T10:30:00Z\",\n \"booking\": [\n {\n \"id\": \"12345678-1234-1234-1234-123456789012\",\n \"venueId\": \"87654321-4321-4321-4321-210987654321\",\n \"date\": \"2025-06-25\",\n \"time\": \"19:30:00\",\n \"partySize\": 4,\n \"status\": \"confirmed\",\n \"reference\": \"REF-20250617-001\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"phone\": \"+1234567890\",\n \"duration\": 120,\n \"notes\": \"Window table preferred\",\n \"createdDate\": \"2025-06-17T09:15:00Z\",\n \"lastUpdate\": \"2025-06-17T10:30:00Z\"\n }\n ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"booking-status-values","__idx":11},"children":["Booking status values"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pending"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Awaiting operator confirmation"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["confirmed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Booking confirmed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelled"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Booking cancelled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Booking completed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no_show"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Guest did not show up"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"signature-verification","__idx":12},"children":["Signature verification"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every webhook request includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header containing an HMAC-SHA256 hex digest of the raw request body, signed with your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secretKey"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verification steps:"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Read the raw request body as a string (before any JSON parsing)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compute ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HMAC-SHA256(secretKey, rawBody)"]}," and hex-encode it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Compare the result to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-API-Key"]}," header using a timing-safe comparison"]}]},{"$$mdtype":"Tag","name":"Cards","attributes":{},"children":[{"$$mdtype":"Tag","name":"Card","attributes":{"title":"⚠️ Use the raw body"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always compute the signature on the raw request body string, not a re-serialised version of the parsed JSON — key ordering and whitespace must be identical."]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling--retries","__idx":13},"children":["Error handling & retries"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint should return appropriate HTTP status codes:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Success — event processed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad request — invalid payload"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized — signature invalid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server error — processing failed"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Failed deliveries are retried with exponential backoff: 1, 2, 4, 8, 16, and 32 minutes. After 6 attempts the event is dropped and logged for review."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"best-practices","__idx":14},"children":["Best practices"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS only"]}," — never register an HTTP callback URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Verify every request"]}," — always validate the signature before processing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respond quickly"]}," — return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]}," immediately and process the event asynchronously if needed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle duplicates"]}," — retries can deliver the same event more than once; make your handler idempotent"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Log everything"]}," — store raw payloads for debugging and auditing"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":15},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Check"},"children":["Check"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not receiving events"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Is your callback URL publicly reachable over HTTPS? Does it return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204"]},"?"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Signature mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Are you hashing the raw body before JSON parsing? Is the stored secret correct?"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Auth failures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Are your OAuth2 credentials valid? Is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["audience"]}," set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api.bookabletech.com"]},"?"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Support:"]}," hello@bookabletech.com"]}]},"headings":[{"value":"Webhook Guide","id":"webhook-guide","depth":1},{"value":"Integration flow","id":"integration-flow","depth":2},{"value":"Step 1: Register your webhook","id":"step-1-register-your-webhook","depth":2},{"value":"Obtain an access token","id":"obtain-an-access-token","depth":3},{"value":"Register your callback URL","id":"register-your-callback-url","depth":3},{"value":"Update your callback URL","id":"update-your-callback-url","depth":3},{"value":"Delete your webhook","id":"delete-your-webhook","depth":3},{"value":"Step 2: Implement your webhook endpoint","id":"step-2-implement-your-webhook-endpoint","depth":2},{"value":"Supported event types","id":"supported-event-types","depth":3},{"value":"Full endpoint implementation","id":"full-endpoint-implementation","depth":3},{"value":"Webhook payload","id":"webhook-payload","depth":2},{"value":"Booking status values","id":"booking-status-values","depth":3},{"value":"Signature verification","id":"signature-verification","depth":2},{"value":"Error handling & retries","id":"error-handling--retries","depth":2},{"value":"Best practices","id":"best-practices","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2}],"frontmatter":{"seo":{"title":"Webhook Guide"}},"lastModified":"2026-03-13T09:43:55.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/getting-started/webhook","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}