Your business.
Your connected tools.

Start with a menu request

1. Enable the Developer API add-on for your business.
2. In your business admin, open Settings → API Tokens. Create a token with catalog:read and copy it when shown.
3. Call the API from your server or automation tool. Keep the token out of public websites and source control.

Examples use this application's host, so you can copy them for local testing. Replace the token placeholder in your own terminal.

curl 'https://servedhq.com/api/v1/menu' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Accept: application/json'

There is no built-in API sandbox. Use a dedicated test business locally. Reservation creation can send notifications or create a deposit checkout; configure test mail and payment credentials before experimenting.

Authentication & access

Every operation requires Authorization: Bearer <your-token>. The token selects the business; you do not pass a business ID. The business must be active and its Developer API add-on enabled.

Use the smallest set of scopes needed. Tokens can have an expiry date and can be revoked by deleting them in the admin. Legacy tokens with no stored scopes retain read permissions only.

Rate limit: 60 requests per minute. On a 429 response, wait for the Retry-After interval before retrying.

From availability to a booking request

Use service IDs and option IDs returned by the catalogue. Check a date in the business's local timezone, then confirm the service, time and customer details with the customer before submitting.

Served HQ calculates prices and duration and checks availability again when you submit. A slot response is not a reservation or a guaranteed hold.

Groups: pass party_size when checking slots. Some businesses can see only a set number of people per time slot; a larger group then needs back-to-back slots, and only start times where the whole run is free are returned. Service prices are per person: each created line reports quantity and unit_price_pence, with price_pence as the line total. Restaurant table bookings are not priced per person.

Some services are enquiry-only and have no booked date. Home visits may require a service address, and businesses may require custom fields. Respect service-specific rules and validation errors.

Use a unique Idempotency-Key for each booking attempt. Reuse it with the same body for network retries. Reusing the key with a changed body returns a conflict.

Webhooks: react to business changes

Served HQ sends an HTTP POST to your receiver when a subscribed event happens. Use it to notify an agent, update a connected dashboard or trigger your automation without polling.

Set up a subscription

1. Enable the business's Developer API add-on and open Webhooks in the business admin.
2. Add your public HTTPS receiver URL and select the events to receive.
3. Copy the subscription's signing secret from the admin and store it on your receiver's server. This is separate from your API bearer token.
4. Run the Served HQ queue worker and trigger a change using a test business. Check the subscription's last delivery status in the admin.

Destinations must use a public HTTPS hostname on port 443 that resolves to public IPv4 addresses. Localhost, private IPs, IPv6-only destinations and redirects are not supported. For local receiving experiments, use a public HTTPS tunnel to your test receiver; never disable destination validation.

What arrives at your endpoint

The JSON envelope contains event, id (UUID), timestamp (ISO 8601 event time) and data. The body and event ID stay the same across retries; the delivery timestamp header and V2 signature are regenerated. Validate freshness against the header timestamp, not the event timestamp in the body.

Events & payload examples

These are illustrative payloads, not a live delivery log. Events contain a subset of record fields. Use the matching GET order or reservation endpoint with its read scope and add-on to retrieve more details.

{
    "event": "order.created",
    "id": "f41e0981-349d-4ef4-9c01-37a66fa272d3",
    "timestamp": "2026-10-06T12:00:00+00:00",
    "data": {
        "order_id": 123,
        "status": "pending",
        "total_pence": 2450,
        "customer_name": "Alex Morgan",
        "order_type": "collection"
    }
}

{
    "event": "order.status_updated",
    "id": "f41e0981-349d-4ef4-9c01-37a66fa272d3",
    "timestamp": "2026-10-06T12:00:00+00:00",
    "data": {
        "order_id": 123,
        "old_status": "confirmed",
        "new_status": "preparing"
    }
}

{
    "event": "reservation.created",
    "id": "f41e0981-349d-4ef4-9c01-37a66fa272d3",
    "timestamp": "2026-10-06T12:00:00+00:00",
    "data": {
        "reservation_id": 456,
        "customer_name": "Alex Morgan",
        "reserved_date": "2026-10-07",
        "reserved_time": "10:30",
        "party_size": 1,
        "service_items": [
            {
                "menu_item_id": 42,
                "service_name": "Consultation",
                "duration_minutes": 30
            }
        ]
    }
}

{
    "event": "reservation.confirmed",
    "id": "f41e0981-349d-4ef4-9c01-37a66fa272d3",
    "timestamp": "2026-10-06T12:00:00+00:00",
    "data": {
        "reservation_id": 456,
        "customer_name": "Alex Morgan"
    }
}

{
    "event": "reservation.cancelled",
    "id": "f41e0981-349d-4ef4-9c01-37a66fa272d3",
    "timestamp": "2026-10-06T12:00:00+00:00",
    "data": {
        "reservation_id": 456,
        "customer_name": "Alex Morgan",
        "reason": "Customer requested cancellation"
    }
}

No dedicated stock-change, payment-settled, refund or reservation-rescheduled event is currently offered. Subscription creation, pausing and deletion happen in the admin; they are not API operations.

Verify the signature

Read the raw HTTP body before decoding JSON. Check the timestamp is within five minutes of your server's clock, calculate the V2 HMAC and compare in constant time. Changing whitespace or re-encoding the JSON before verification will invalidate the signature.

PHP example: pass $request->getContent(), the timestamp and V2 headers, and your stored secret to this function. Reject invalid requests before applying any business changes. Use the event name in the signed body for routing.

<?php

// Signature verification only; call this with the exact, unmodified HTTP body.
// Load the subscription's secret from secure server-side configuration.
function verifyServedHqWebhook(
    string $rawBody,
    string $timestamp,
    string $signatureV2,
    string $secret,
    ?int $now = null,
): array {
    if ($secret === '' || ! ctype_digit($timestamp)
        || abs(($now ?? time()) - (int) $timestamp) > 300
        || ! preg_match('/\A[a-f0-9]{64}\z/', $signatureV2)) {
        throw new RuntimeException('Invalid webhook authentication.');
    }

    $expected = hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);
    if (! hash_equals($expected, $signatureV2)) {
        throw new RuntimeException('Invalid webhook signature.');
    }

    $event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
    if (! is_array($event) || ! is_string($event['id'] ?? null)
        || ! is_string($event['event'] ?? null) || ! is_array($event['data'] ?? null)) {
        throw new RuntimeException('Invalid webhook envelope.');
    }

    // Receiver must now persist using a unique (subscription, event ID) key.
    // A valid signature alone does not prevent duplicate processing.
    return $event;
}

Acknowledge, deduplicate & retry

1. Verify the request, then durably store it using a unique key combining the subscription identity and event id.
2. Return a 2xx response promptly after storing it, including for an already stored duplicate. Process the stored event asynchronously.
3. Do not rely on delivery order. Reconcile the current record through the read API where needed.

Delivery has a 5-second connection timeout and a 10-second request timeout. The job permits up to three attempts total; normal queued retry delays are 10 seconds and then 60 seconds. Worker configuration can affect retry timing or reduce attempts. Non-2xx responses and network failures cause retries; redirects are rejected.

After retries are exhausted, delivery can be lost. Monitor the last delivery status and reconcile records through the read API; there is no public webhook delivery-history or replay endpoint. Disabled/deleted subscriptions, inactive businesses and disabled or expired Developer API access stop delivery.

Errors & retries

Errors can contain error and a machine-readable code. Validation errors use message and field-level errors.

Lists return data and pagination meta: current page, last page and total. Use page and per_page (default 25, maximum 100).

Response & request schemas

Expand a schema to inspect its fields. Follow linked types for nested records.

{
    "type": "object",
    "required": [
        "group_id",
        "option_ids"
    ],
    "properties": {
        "group_id": {
            "type": "integer"
        },
        "option_ids": {
            "type": "array",
            "items": {
                "type": "integer"
            }
        }
    }
}

What you can build today

Connect a booking agent to services and availability, submit reservation requests, or build a dashboard/export that reads your menu, orders and reservations.

Need help with an integration? Talk to Served HQ →