Webhooks
A webhook is an https address on your server that Dropoint calls when a delivery changes. Add it on the store portal (Developers › Webhooks) or with POST https://api.dropoint.co.ke/api/integrations/v1/stores/webhooks/ (url, events). The answer gives the secret once.
Events#
| Event | When |
|---|---|
order.awaiting_approval | A website order arrived |
order.approved | The store approved it |
order.rejected | The store rejected it (delivery.rejected_reason) |
order.ready | Marked ready and sent: a rider is being found |
order.ready_blocked | Marked ready, but the wallet couldn't pay; it will be sent after a top-up |
order.expired | Nobody handled it in time |
order.created | The real order was made (right after order.ready) |
order.assigned | A rider is coming |
order.picked_up | The parcel left the shop |
order.delivered | Delivered |
order.failed | Couldn't deliver |
order.cancelled | Cancelled |
order.returned | Back at the shop |
order.status_changed | Subscribe to get every change, including the ones above |
What arrives#
POST /dropoint-webhook HTTP/1.1
Content-Type: application/json
X-Dropoint-Event: order.ready
X-Dropoint-Delivery: 2b9d… (the same on every retry: ignore repeats)
X-Dropoint-Timestamp: 1763806800
X-Dropoint-Signature-V2: t=1763806800,v1=5f0c…
X-Dropoint-Signature: sha256=91aa… (older form, body only)
{"event": "order.ready", "sent_at": 1763806800, "test": false,
"delivery_id": "b3e2…", "reference": "WC-1041", "channel": "woocommerce", "stage": "sent",
"delivery": {"stage": "sent", "customer": {…}, "fee": {…}, "tracking_url": "…",
"order": {"number": "DRP-…", "status": "broadcasting"}}}
Events about the real order (order.assigned and after) carry order at the top level too, with the rider, picked_up_at and delivered_at.
Check the signature#
Take the raw body, compute HMAC-SHA256 of "<timestamp>.<raw body>" with your secret, and compare it with v1. Refuse messages older than 5 minutes.
<?php
$secret = getenv('DROPOINT_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_DROPOINT_SIGNATURE_V2'] ?? ''), $sig);
$expected = hash_hmac('sha256', $sig['t'] . '.' . $body, $secret);
if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) $sig['t']) > 300) {
http_response_code(400); exit;
}
$event = json_decode($body, true);
// … update your order using $event['reference'] …
http_response_code(204);
// Node (Express): use the raw body, not parsed JSON
const crypto = require('crypto');
app.post('/dropoint-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const parts = Object.fromEntries((req.get('X-Dropoint-Signature-V2') || '').split(',').map((p) => p.split('=')));
const expected = crypto.createHmac('sha256', process.env.DROPOINT_WEBHOOK_SECRET)
.update(`${parts.t}.${req.body}`).digest('hex');
const ok = parts.v1 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
&& Math.abs(Date.now() / 1000 - Number(parts.t)) <= 300;
if (!ok) return res.sendStatus(400);
const event = JSON.parse(req.body);
// … update your order using event.reference …
res.sendStatus(204);
});
# Python (Django)
import hashlib, hmac, json, os, time
from django.http import HttpResponse
def dropoint_webhook(request):
parts = dict(p.split("=", 1) for p in request.headers.get("X-Dropoint-Signature-V2", "").split(",") if "=" in p)
expected = hmac.new(os.environ["DROPOINT_WEBHOOK_SECRET"].encode(),
parts.get("t", "").encode() + b"." + request.body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, parts.get("v1", "")) or abs(time.time() - int(parts.get("t", 0))) > 300:
return HttpResponse(status=400)
event = json.loads(request.body)
# … update your order using event["reference"] …
return HttpResponse(status=204)
Delivery rules#
- Answer any 2xx within 5 seconds. Do slow work after answering.
- No 2xx: Dropoint tries again after 1, 5, 30 and 120 minutes. The same
X-Dropoint-Deliveryid is sent each time: ignore repeats. - After 50 failed deliveries in a row the webhook is switched off and the store owner is told.
- Messages can arrive out of order: use
sent_atand thestatusin the message, not the order of arrival. - Addresses must be public https. The portal's Deliveries list shows every message, your answer, and Send again.