Webhooks

A webhook tells your server when an order or a reservation changes, so your server does not have to keep asking. This guide covers setting one up, the events that arrive, checking their signature and the rules of delivery.

Setting up a webhook#

A webhook belongs to an API key. The venue's owner enters its address in the panel, on the key:

1. On the API Keys page, select Edit beside the key. You can also enter the address while creating a new key.
2. In Webhook address, enter the address on your server that will receive the events: a public https:// address.
3. When you save, the signing secret (whsec_…) is shown once. Copy it into your server's configuration.

• New Secret creates a new secret, and the old one stops working at once. Put the new secret on your server straight away, or the signatures of incoming notifications cannot be checked.
• Clearing the address removes the webhook and its signing secret together. No event is sent for a key with no address.

An order's event usually arrives within seconds. When Cibusy is idle it can take up to about a minute, because a sweep that runs once a minute is what delivers it then. A reservation's event is always delivered by that sweep, within about a minute: a reservation does not change by the second, but when somebody decides something. Do not build anything that relies on an event being instant.

Which orders are followed#

A key's webhook follows the orders that key placed, or added a round to.

• The first order.updated for an order is sent when the order is placed, with the order as it started.
• An order is followed for 48 hours after it was placed. A change after that is not announced; GET /orders/{orderId} keeps telling you its state.
• An address added to a key later starts receiving the updates of that key's open orders from the last 48 hours.
• No events are sent for the orders of a revoked key.

Any change to the order as the API shows it is an event: its status, payment status, table, total, the amount paid, when it was closed, or its lines being added, or their quantity or status changing. A name or a note corrected on the venue's side is not one.

Which reservations are followed#

A key's webhook follows the reservations that key took as well; the Can take reservations permission is all the key needs for it.

• The first reservation.updated for a reservation is sent after it is taken, with the reservation as it was made.
• Later events come when the venue accepts or declines the request; when the reservation is called off by the guest, by the venue or for want of an answer; when the guest is checked in at the door; and when the visit ends or nobody came.
• A reservation is followed from the day it is made until 48 hours after the time it was for; following ends once it is declined, called off or over and that last state was delivered. After that, GET /reservations/{reservationId} keeps telling you its state.
• An address added to a key later starts receiving the updates of the reservations that key still has open.
• No events are sent for the reservations of a revoked key.

The changes that make an event are the reservation's status, its time, its number of guests and who called it off. A note the venue corrects is not one.

Events#

Each event is a JSON body written by the same rules as the rest of the API (camelCase names, enum names, UTC times), sent compactly in UTF-8 without a byte-order mark. It is shown indented here, to be read:

{
  "id": "evt_0f8e2c1a7d444b0e9d2a5c3e7b1f9a60",
  "type": "order.updated",
  "createdAt": "2026-10-01T09:42:17.481Z",
  "data": { }
}

• id is evt_ followed by 32 lowercase hexadecimal characters. The id of an order.updated or reservation.updated event stays the same every time the same change to the same order or reservation is delivered again, and differs for every new change: it is what to de-duplicate on. A webhook.test event has a new id every time.
• createdAt is when Cibusy prepared that delivery.

The fields of order.updated#

The fields of reservation.updated#

The fields of webhook.test#

The request's headers#

Cibusy sends a POST to your address with these headers:

Verifying the signature#

Check every delivery before you act on it. The signature proves that the body came from Cibusy and was not changed on the way.

1. Read the raw body of the request: the exact bytes received, before any JSON parser has touched them. Verify first, then parse; re-serialising parsed JSON does not give the same bytes.
2. Split the X-Cibusy-Signature header on , and read t (a Unix timestamp in seconds) and v1.
3. Reject the request if t is more than 5 minutes from your own clock. This stops an old delivery being replayed. Every retry has a t of its own, so a delivery that is retried passes.
4. Compute the HMAC-SHA256 of the message t + . + the raw body, with the whole signing secret as the key, exactly as the panel showed it, including the whsec_ prefix. Take the UTF-8 bytes of the secret and of the message, and write the result as lowercase hexadecimal.
5. Compare it with v1 in constant time.

<?php
$secret  = getenv('CIBUSY_WEBHOOK_SECRET');      // whsec_...
$rawBody = file_get_contents('php://input');     // the exact bytes received
$header  = $_SERVER['HTTP_X_CIBUSY_SIGNATURE'] ?? '';

$parts = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
    $parts[$key] = $value;
}
$timestamp = $parts['t'] ?? '';
$signature = $parts['v1'] ?? '';

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!ctype_digit($timestamp)
    || abs(time() - (int) $timestamp) > 300
    || !hash_equals($expected, $signature)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);
// De-duplicate on $event['id'], then handle the event.
http_response_code(204);

Test vector#

Check your code against this: a webhook.test event as Cibusy writes it, signed with a secret made up for the purpose. Its t is 1 October 2026 09:30:00 UTC, so step 3 rejects it unless your test sets the clock to that time or leaves that one check out.

secret    whsec_PVJ2W1xHqfX6u1b0Jg9eT3nR5s8dKzYaLmQwEoCtUiA
body      {"id":"evt_3f2a9c4e8b1d4f6a9e0c7b5d2a1f8e34","type":"webhook.test","createdAt":"2026-10-01T09:30:00.000Z","data":{"venueId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","keyPrefix":"cbk_a1B2c3D4","message":"This is a test event from Cibusy. No order has changed."}}
header    t=1790847000,v1=0d704c590d7d639a6658090e4fbb189e4e4e0e410319f007cd509ad2e67c36c9

Delivery and retries#

• Answer 2xx quickly. A 2xx status means the event is delivered. Anything else is a failure: another status, a redirect (which is not followed), a connection that takes more than 5 seconds to open, an answer that takes more than 10 seconds in all, or a connection error. Do the work after you have answered.
• Retries. After a failure Cibusy tries again, up to 9 attempts for the same change, waiting 30 seconds, then 1, 2, 4, 8, 16, 32 and 64 minutes between them: about two hours in all. It then stops trying for that change and sends nothing more until the order or the reservation changes again. A reservation's events are retried on the same schedule. Every attempt is signed afresh, with a t of its own.
• De-duplicate. A retry, and rarely a delivery that was already received, brings the same id again. Remember the ids you have handled and ignore a repeat.
• Read the state, not the history. An event carries the order or the reservation as it was when that delivery was prepared. Deliveries about one order or reservation can arrive out of order: compare createdAt with what you hold, or, when you are unsure which is newer, read it as it is now with GET /orders/{orderId} or GET /reservations/{reservationId}.
• The address. It must be https://, with a public host name or address. Addresses that point at private, loopback, link-local or cloud-metadata destinations are refused, both when the address is saved and when an event is sent, and a redirect is never followed.
• The sending IP address. Cibusy does not publish the addresses events come from. What proves a delivery is genuine is the signature, not the IP address.

Testing#

POST /webhooks/test sends a webhook.test event to the key's address, signed as a real one is, and says what your server did. The key needs either the Can send orders or the Can take reservations permission:

curl -X POST "https://api.cibusy.com/public/v1/webhooks/test" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

{ "delivered": true, "statusCode": 204, "error": null, "durationMs": 182 }

• The answer is 200 whether or not your server accepted the event; delivered says which.
• statusCode is the status your server answered with, and null when it did not answer at all. error is null when the event was delivered, and otherwise says in a short sentence what went wrong.
• The call waits for your server's answer for up to 10 seconds. A test event is not retried.
• A key with no webhook address is answered 409 PUBLIC_API_WEBHOOK_NOT_CONFIGURED.
• A test counts against the budget of about 30 requests a minute the key shares with orders and reservations.