Webhooks
Get notified the moment a delivery changes status.
Instead of polling, give Katch an HTTPS endpoint and we will POST the full task to it on every status change.
Setup
Send your endpoint URL to your Katch account manager. It is registered once per API key and applies to every task created with that key.
Delivery
- Method:
POST(unless agreed otherwise) - Body: the full task object as JSON (example below)
- Events: one request per status change:
accepted,inprogress,pickup_location_reached,pickedup,enroute,delivered,cancelled - Timeout: your endpoint must respond within 5 seconds
Respond fast, process later
Failed or slow deliveries are not retried today. Return 200 immediately, queue the payload, and process it in the background. Use Get a task by ID to reconcile if you suspect you missed an event.
Request signing is coming
Webhook requests are not signed yet. Until signing ships, treat the payload as a hint: confirm important changes (for example delivered before releasing payment) by fetching the task with your API key.
Example payload
Event for a delivered task. Your code should ignore fields it does not recognise; new fields may be added at any time.
{
"driver": {
"name": "Ahmad",
"phone": "96550000002",
"trackingLink": "https://tracking.katchkw.com/task/WDXS-1816",
"completed_at": "2026-10-05T10:10:36.016Z"
},
"deliveryLocation": {
"lat": 29.192541471993156,
"lng": 48.09227342570171,
"kwAddress": [
"Mubarak Al Kabeer Governorate",
"Mubarak Al-Kabeer",
"St 14",
"8"
],
"fullAddress": [
"Mubarak Al Kabeer, block 8, St 14, bldg 3"
]
},
"pickupLocation": {
"longitude": 48.043169191807124,
"latitude": 29.339765988185306,
"fullAddress": [
"Hawally, block , St baghdad, bldg "
]
},
"_id": "6ac36d78e073cc5fbc0ea750",
"sellerId": "YOUR_SELLER_ID",
"sellerName": "Your Store",
"orderNumber": "PJEI-3812",
"customerName": "Jane Doe",
"customerNumber": "96550000000",
"alternateCustomerNumber": "",
"deliveryZone": "Mubarak Al Kabeer, block 8, St 14, bldg 3",
"collectCash": false,
"totalAmount": "4.7",
"status": "delivered",
"vehicleType": "bike",
"customPickup": true,
"pickupName": "Your Store",
"pickupNumber": "96550000001",
"travelDetail": {
"totalDistance": 20503,
"duration": 1055,
"durationInTraffic": 0,
"hasTraffic": false,
"estimatedDelayByTraffic": 0
},
"estimatedPrice": "1.750",
"walletDeducted": true,
"statusHistory": [
{
"status": "pending",
"timestamp": "2026-10-05T09:27:20.302Z"
},
{
"status": "accepted",
"timestamp": "2026-10-05T09:30:52.523Z"
},
{
"status": "inprogress",
"timestamp": "2026-10-05T09:31:42.385Z"
},
{
"status": "pickedup",
"timestamp": "2026-10-05T09:45:48.412Z"
},
{
"status": "enroute",
"timestamp": "2026-10-05T10:01:03.574Z"
},
{
"status": "delivered",
"timestamp": "2026-10-05T10:10:36.022Z"
}
],
"deliveryId": "WDXS-1816",
"createdAt": "2026-10-05T09:27:20.305Z",
"updatedAt": "2026-10-05T10:10:36.023Z",
"deliveryDispatched": true
}Handling it
app.post('/katch/webhook', express.json(), (req, res) => {
res.sendStatus(200); // ack first
queue.add('katch-task-update', {
deliveryId: req.body.deliveryId,
orderNumber: req.body.orderNumber,
status: req.body.status,
});
});