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_delivery

Orders

order.createdorder.acceptedorder.readyorder.completedorder.canceled

Catalogue

product.approvedproduct.rejectedproduct.publishedimport.completed

Billing

tokens.lowtokens.exhaustedinvoice.paidinvoice.failedsubscription.renewed

Account

org.status_changed

Payload 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 2xx within 5 seconds. Timeouts and 5xx count as failures.
  • Retries: 15s → 1m → 5m → 30m → 2h → 8h. After the last attempt the delivery is marked exhausted and you (and our ops team) get notified.
  • Events may arrive out of order or more than once. Deduplicate on eventId and use data.updatedAt for 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.