Chauffeur Circle Docs

Developers

Webhooks

Business Included on these plans

Chauffeur Circle can POST an event to your server whenever a booking or payment changes, so your own systems (dispatch, CRM, accounting) stay in sync.

Add an endpoint

  1. In the dashboard, open Webhooks and add your HTTPS URL.
  2. Choose the events, or all of them.
  3. Copy the signing secret (whsec_…). It is shown once.
  4. Press Send test to receive a webhook.test event.

Events

Event When
booking.created A booking or quote request was made. Priced bookings start as pending_card; payment.card_saved follows when the card is saved
booking.accepted You accepted it
booking.declined You declined it
booking.updated Trip details changed
booking.cancelled The passenger or you cancelled it
booking.no_show You marked it as a no-show
booking.completed You completed it and the final amount was charged
payment.card_saved The passenger saved a card
payment.hold_placed The card was held before pickup
payment.hold_failed The hold was refused; the passenger was asked to update the card
payment.captured A charge succeeded (ride, cancellation fee or no-show fee)
payment.refunded You refunded a payment

Payload

{
  "id": "evt_6f1c2a8e-…",
  "type": "booking.accepted",
  "created_at": "2026-06-02T14:05:11+00:00",
  "livemode": true,
  "data": {
    "booking": { "reference": "MBC-7K2Q9X", "status": "accepted", "pickup_at": "…", "customer": { "first_name": "Ada", "email": "…" }, "…": "…" }
  }
}

data.booking is the booking as the API returns it, plus the booker's contact details. Payment events also include data.payment. Card details are limited to brand and last four digits.

Verify the signature

Every request has a Chauffeur-Circle-Signature header:

Chauffeur-Circle-Signature: t=1780408511,v1=5f2b…

v1 is the hex HMAC-SHA256 of "{t}.{raw request body}" with your signing secret. Check it against the raw body (before JSON parsing) and reject old timestamps.

Node (with the SDK):

import { ChauffeurCircle } from '@chauffeurcircle/js';

app.post('/chauffeur-circle', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = await ChauffeurCircle.webhooks.verify(process.env.CHAUFFEUR_CIRCLE_WEBHOOK_SECRET, req.get('Chauffeur-Circle-Signature'), req.body.toString());
  if (!ok) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  // handle event.type …
  res.sendStatus(200);
});

PHP:

$header = $_SERVER['HTTP_CHAUFFEUR_CIRCLE_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $header), $parts);

$valid = isset($parts['t'], $parts['v1'])
    && abs(time() - (int) $parts['t']) <= 300
    && hash_equals(hash_hmac('sha256', $parts['t'].'.'.$body, getenv('CHAUFFEUR_CIRCLE_WEBHOOK_SECRET')), $parts['v1']);

if (! $valid) { http_response_code(400); exit; }

Delivery and retries

  • Respond with any 2xx within 10 seconds. Do slow work after responding.
  • Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marked failed.
  • The same event can arrive more than once. Use id to ignore duplicates.
  • Events can arrive out of order. Use created_at, or fetch the booking from the API, when order matters.
  • See every delivery and its response in Webhooks → Deliveries.

URLs must be public HTTPS addresses; private and local addresses are refused.