Webhooks that tell you
exactly what happened.

Point Carte at your endpoint

1. In your admin, open Integrations and choose Webhooks for your own endpoint — or Zapier, Make or n8n for those platforms' catch hooks.
2. Paste your URL. It must be a valid absolute <code>http://</code> or <code>https://</code> URL; anything else is ignored silently rather than saved and quietly never fired.
3. Set a signing secret. On the Webhooks connector this is expected; on Zapier, Make and n8n it is optional — leave it blank and deliveries go unsigned.
4. Press Test connection. That sends a real <code>ping</code> event to your URL right now — the fastest way to prove your route and your signature check work before real traffic arrives.
5. Configure as many as you like. Every configured target receives every event: there is no per-event subscription and no filtering. Ignore what you don't need by switching on <code>event</code>.

The envelope

Every event — all nine — is a POST with Content-Type: application/json, User-Agent: Carte-Webhook/1.0, and this outer shape. Only data changes. sent is an ISO-8601 timestamp in the server's timezone.

{
  "event": "menu.published",
  "venue": { "slug": "the-copper-pot", "name": "The Copper Pot" },
  "data":  { "menu": { "id": "mdinner01", "name": "Dinner — Spring" } },
  "sent":  "2026-07-16T09:12:00+00:00"
}

The nine events

Every configured target receives every event — there is no subscription model. Switch on event and ignore the rest. Each block below shows the data object only; wrap it in the envelope above.

{ "menu": { "id": "mdinner01", "name": "Dinner — Spring" } }

{ "menu": { "id": "mdinner01", "name": "Dinner — Spring" } }

{
  "dish": { "id": "d7321b40e4b", "name": "Cured chalk-stream trout", "available": false },
  "menu": { "id": "mdinner01", "name": "Dinner — Spring" }
}

{
  "booking": {
    "ref": "BK-YSXGBS",
    "status": "confirmed",
    "source": "widget",
    "date": "2026-08-14",
    "party": 2
  }
}

{
  "booking": { "ref": "BK-YSXGBS", "status": "cancelled", "guest": "Ana Petrova" }
}

{ "voucher": { "code": "GV-4K2P-9QX7", "value": 50 } }

{ "voucher": { "code": "GV-4K2P-9QX7", "amount": 20, "balance": 30 } }

{ "message": "Carte connection test" }

{
  "items": [
    { "id": "d7321b40e4b", "name": "Cured chalk-stream trout", "desc": "pickled fennel, buttermilk, dill oil", "price": 12.5 },
    { "id": "w173b9cb432", "name": "Bin 34 — Meursault 2021", "desc": "Domaine Roulot · White — taut, mineral", "price": 86 }
  ]
}

Verifying the signature

When a signing secret is set, Carte sends an <code>X-Carte-Signature</code> header: the string <code>sha256=</code> followed by the hex HMAC-SHA256 of the raw request body, keyed with your secret. Verify it on the bytes you received — parsing the JSON and re-encoding it changes whitespace and key order, and the HMAC will not match. Compare in constant time.

X-Carte-Signature: sha256=3f9a1c2b8e...

<?php
// Your endpoint. Read the RAW body — not $_POST, not a re-encoded array.
$raw    = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_CARTE_SIGNATURE'] ?? '';
$secret = getenv( 'CARTE_WEBHOOK_SECRET' );

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

// hash_equals, not === : constant time, so a timing attack cannot walk the HMAC.
if ( ! hash_equals( $expected, $header ) ) {
    http_response_code( 401 );
    exit;
}

// Acknowledge FIRST — you have 5 seconds. Queue the work, do not do it here.
http_response_code( 200 );

$event = json_decode( $raw, true );
switch ( $event['event'] ) {
    case 'menu.published':
        // $event['data']['menu']['id']
        break;
    case 'booking.created':
        // ref, status, source, date, party — the same fields from every origin
        break;
}

const crypto = require('crypto');

// express: mount the RAW body, or the HMAC will never match.
app.post('/hooks/carte', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.CARTE_WEBHOOK_SECRET)
    .update(req.body)                       // Buffer, exactly as received
    .digest('hex');

  const got = req.get('X-Carte-Signature') || '';
  const ok  = expected.length === got.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));

  if (!ok) return res.sendStatus(401);
  res.sendStatus(200);                      // acknowledge first

  const event = JSON.parse(req.body.toString('utf8'));
  queue.push(event);                        // then do the work
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/carte")
def carte_hook():
    raw = request.get_data()               # bytes, exactly as received
    expected = "sha256=" + hmac.new(
        os.environ["CARTE_WEBHOOK_SECRET"].encode(),
        raw,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, request.headers.get("X-Carte-Signature", "")):
        abort(401)

    queue.push(request.get_json())         # acknowledge by returning fast
    return "", 200

Delivery guarantees, stated honestly

Delivery is best-effort by design. Read this before you build anything that must not miss an event.

• No retries. Every event is delivered exactly once, attempted once. If your endpoint is down, restarting, or returns a 500, that event is gone — Carte does not try again and does not queue it. Anything that must not be missed should be reconciled against the REST API on a schedule, not driven by webhooks alone.
• Short timeouts. 3 seconds to connect, 5 seconds total. Acknowledge fast and do the work afterwards; if you process inline and take six seconds, the delivery is recorded as failed even though you handled it.
• Any 2xx is success. Anything else — including a 3xx — is logged as an error. Redirects are not followed.
• Delivery is synchronous. Events fire inside the request that caused them, so a slow endpoint of yours makes a member of staff wait for their menu to publish. There is no queue and no background worker.
• No ordering guarantee, no delivery ids. Events carry no sequence number and no unique id. Two rapid changes can arrive out of order. Use <code>sent</code> and your own idempotency key if that matters to you.
• Every attempt is logged. Success or failure, with the HTTP status, in your Integrations sync log — the first place to look when an automation goes quiet.

Keep reading

• REST API reference — the nine endpoints, and how to reconcile what a missed webhook lost.
• Integrations reference — every connector, live or simulated.