Dropoint for developers

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#

EventWhen
order.awaiting_approvalA website order arrived
order.approvedThe store approved it
order.rejectedThe store rejected it (delivery.rejected_reason)
order.readyMarked ready and sent: a rider is being found
order.ready_blockedMarked ready, but the wallet couldn't pay; it will be sent after a top-up
order.expiredNobody handled it in time
order.createdThe real order was made (right after order.ready)
order.assignedA rider is coming
order.picked_upThe parcel left the shop
order.deliveredDelivered
order.failedCouldn't deliver
order.cancelledCancelled
order.returnedBack at the shop
order.status_changedSubscribe 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-Delivery id 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_at and the status in 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.
Base address: https://api.dropoint.co.ke/api/integrations/v1 · Questions? Use Support on the store portal.