Developers
Webhooks
Get signed change notices on your own HTTPS receiver when bookings, orders or invoices change.
On this page
Outbound webhooks send a small, signed JSON notice to your HTTPS receiver when something changes in CaterCamp. They are available on the Business plan and during the free trial, and are managed in Settings → Webhooks by owners and administrators with settings access.
A notice is a change hint. It names what changed (for example a booking or invoice ID), and your system then reads the current record with a Business API key.
Setting up a receiver
- In Settings → Webhooks, choose Add endpoint. Enter your HTTPS URL, the notice types you want and the data boundary (whole workspace or selected locations).
- Copy the signing secret. It is shown once and starts with
ccwhsec_. - Verify the receiver. CaterCamp sends a challenge; your receiver must answer with a
2xxresponse that includes aCaterCamp-Webhook-Challengeheader equal todata.challengefrom the request body, within ten seconds. - Approve sharing. Nothing is sent until the receiver is verified and you confirm what it may receive.
You can pause, resume or permanently revoke an endpoint at any time. Pausing and revoking stop new sends; an attempt already in flight cannot be recalled.
Request format
Each delivery is an HTTPS POST with a JSON body (at most 64 KiB) and these headers:
| Header | Meaning |
|---|---|
CaterCamp-Signature | t=<Unix seconds>,v1=<hex HMAC-SHA256> |
CaterCamp-Event-Id | Stable ID of the change. Use it to deduplicate. |
CaterCamp-Delivery-Id | Stable for one notice to one endpoint. |
CaterCamp-Attempt-Id | New for each attempt. |
User-Agent | CaterCamp-Webhooks/1 |
The body contains the event ID, workspace ID, occurrence time, API version, notice type and the resource IDs. It never contains client contact details, addresses, prices, notes, mail or financial ledgers.
{
"id": "<event ID>",
"apiVersion": "2026-10-24",
"workspaceId": "<workspace ID>",
"occurredAt": "2026-12-01T15:04:05.000Z",
"type": "invoice.issued",
"data": { "invoiceId": "<invoice ID>" }
}
Verifying signatures
Verify every request before you trust it:
- Take the part of your secret after
ccwhsec_and base64url-decode it into a 32-byte key. - Compute HMAC-SHA256 with that key over the timestamp, a period (
.) and the exact raw request body bytes, before parsing JSON. - Compare your result with
v1using a constant-time comparison. - Reject requests whose timestamp is more than five minutes from your clock.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(rawBody, secret, header) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? "");
if (!match) return false;
const [, t, v1] = match;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const key = Buffer.from(secret.slice("ccwhsec_".length), "base64url");
const expected = createHmac("sha256", key)
.update(`${t}.`)
.update(rawBody)
.digest();
return timingSafeEqual(expected, Buffer.from(v1, "hex"));
}
Retries and duplicates
- Only a complete
2xxresponse acknowledges a notice. Failed attempts are retried up to eight times with backoff over roughly 45 hours; a notice expires after 72 hours. - Redirects, invalid TLS, private network addresses and most
4xxresponses stop retries and show the endpoint as needing review. - Notices can arrive more than once or out of order. Deduplicate on the event ID inside the signed body, and keep those records for at least 31 days.
- You can redeliver a notice from the endpoint's delivery history up to three times within 30 days.
- To catch up after downtime, read retained notices with
GET /api/v1/webhook-endpoints/:id/noticesusing a key withwebhooks:readand the matching data permission (up to 30 days per request).
Notice types
| Type | When it is sent |
|---|---|
event.created / event.deleted | A booking was created or deleted. |
event.details.changed | Booking details changed (lists changed field names). |
event.status.changed | The booking's status changed. |
event.meals.changed | The meal schedule changed (lists added, updated or removed meal IDs). |
event.order.updated | The working order changed. |
event.business.changed | The booking's location or brand changed. |
event.scope.left | A booking left this receiver's location boundary. |
event.guarantee.changed | The guest guarantee or its confirmation changed. |
event.instructions.published / .withdrawn / .acknowledged | Customer instructions were shared, recalled or acknowledged. |
event.proposal.accepted / event.proposal.declined | A customer accepted or declined a proposal. |
event.change_request.changed / .follow_up_shared | A customer portal change request changed, or the caterer shared a follow-up. |
event.online_request.changed | An online catering request was submitted, revised or decided. |
event.delivery.changed / event.pickup.changed | A delivery or equipment pickup changed. |
event.corporate_request.linked, corporate_request.* | Corporate catering requests were submitted, routed, scheduled or decided. |
branch.catalogue.changed | A location published a catalogue policy. |
invoice.issued, invoice.lifecycle.changed, invoice.schedule.changed, invoice.credit.changed, invoice.payment.changed, invoice.refund.changed, invoice.dispute.changed | An invoice was issued or its status, schedule, credits, payments, refunds or disputes changed. |
Try it with your next real event
Fourteen days with every Business feature. Add one booking, one menu and your team, then choose the plan that fits.
Start your free trial