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
- In the dashboard, open Webhooks and add your HTTPS URL.
- Choose the events, or all of them.
- Copy the signing secret (
whsec_…). It is shown once. - Press Send test to receive a
webhook.testevent.
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
2xxwithin 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
idto 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.