Webhooks
Kolis sends a JSON POST to your URL on every change. Reply 2xx within 8 seconds.
Events
delivery.createdThe delivery is registereddelivery.searchingSearching for a courierdelivery.assignedA courier accepteddelivery.picked_upParcel picked updelivery.deliveredHanded over against the codedelivery.cancelledCancelled (reason provided)delivery.failedFailed after pickupdelivery.delayedDelay reported by the courier (data.delivery.delay_minutes cumulative, delay_reason)
{
"id": "evt_3f9a…",
"type": "delivery.assigned",
"api_version": "2026-11-01",
"created": "2026-11-10T10:04:12Z",
"mode": "live",
"data": { "delivery": { "id": "7CAE5146", "external_ref": "CMD-1042", "status": "assigned", "reason": null } }
}import { verifyWebhookSignature } from "./kolis";
app.post("/hooks/kolis", express.raw({ type: "*/*" }), (req, res) => {
const ok = verifyWebhookSignature(process.env.WHSEC, req.header("x-kolis-signature"), req.body.toString());
if (!ok) return res.sendStatus(400);
// dédoublonner avec x-kolis-event-id, puis répondre vite
res.sendStatus(200);
});Reliability
- SignatureX-Kolis-Signature : t=…,v1=… (HMAC-SHA256)
- DuplicatesX-Kolis-Event-Id is identical on each retry
- RetriesAfter 1, 5, 30, 120, 720 minutes
- Secret rotationTwo signatures for 24 h
- OrderNot guaranteed: use the created field