Webhooks
Webhooks push lifecycle events to your servers the moment they happen — no polling. Payloads are HMAC-signed, retried with exponential backoff for 24 hours, and replayable from the portal for 30 days.
Event catalogue
Deliveries
delivery.createddelivery.status_changeddelivery.rider_assigneddelivery.picked_updelivery.completeddelivery.faileddelivery.canceleddelivery.proof_of_deliveryOrders
order.createdorder.acceptedorder.readyorder.completedorder.canceledCatalogue
product.approvedproduct.rejectedproduct.publishedimport.completedBilling
tokens.lowtokens.exhaustedinvoice.paidinvoice.failedsubscription.renewedAccount
org.status_changedPayload format
example-request
POST https://your-app.com/hooks/quickli HTTP/1.1
Content-Type: application/json
X-Quickli-Event: delivery.status_changed
X-Quickli-Delivery: whd_01J8ZR2P…
X-Quickli-Signature: sha256=3d0c9a…
{
"eventId": "evt_01J8ZQ…",
"event": "delivery.status_changed",
"createdAt": "2026-11-13T14:32:10.000Z",
"environment": "live",
"data": {
"deliveryId": "dlv_01J8ZK3M",
"orderId": "QK-20261113-00482",
"externalId": "INV-1042",
"previousStatus": "rider:accepted",
"status": "rider:picked-up-order",
"rider": { "name": "Musa A.", "rating": 4.9, "vehicle": "Motorcycle" },
"location": { "lat": 6.4531, "lng": 3.3952 },
"updatedAt": "2026-11-13T14:32:09.000Z"
}
}Verifying signatures
Every endpoint you register gets a unique secret (reveal/rotate it in Portal → Webhooks). Sign the raw request body with HMAC-SHA256 and compare against X-Quickli-Signature:
verify.ts
import crypto from "node:crypto";
function verifyQuickliSignature(rawBody, header, secret) {
const expected =
"sha256=" +
crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
// constant-time compare
return crypto.timingSafeEqual(
Buffer.from(header),
Buffer.from(expected)
);
}
// Express: use express.raw() for the webhook route so rawBody matches
app.post("/hooks/quickli", express.raw({ type: "application/json" }), (req, res) => {
const sig = req.get("X-Quickli-Signature");
if (!sig || !verifyQuickliSignature(req.body, sig, process.env.QUICKLI_WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body);
handle(event); // process idempotently by event.eventId
res.status(200).send("OK");
});Delivery semantics
- Your endpoint must respond
2xxwithin 5 seconds. Timeouts and 5xx count as failures. - Retries: 15s → 1m → 5m → 30m → 2h → 8h. After the last attempt the delivery is marked
exhaustedand you (and our ops team) get notified. - Events may arrive out of order or more than once. Deduplicate on
eventIdand usedata.updatedAtfor ordering. - Consecutive failures auto-pause an endpoint after 50 strikes to protect your infrastructure; re-enable with one click after fixing the receiver.
Testing
- Sandbox endpoints (
qk_test_keys) receive sandbox events from the simulated rider timeline — perfect for integration tests. - The portal delivery log supports manual retry and replay of any event from the last 30 days, plus a test-ping button per endpoint.
Best practice
Acknowledge fast (200), process async. Persist the event, return immediately, and handle business logic from a queue. This keeps you well inside the 5-second window even under load.