Skip to content

For developers

API and webhooks

Your web shop or other system sends orders to Routehive as stops, and gets the delivery status back by webhook or by polling. Available in the Pro and Fleet plans.

Machine-readable description (OpenAPI)

Authentication

The owner or an admin creates an API key on the API and webhooks page of the app. The key is shown only once. Send it in the header of every request as a Bearer token. A read-only key cannot add stops.

curl -X POST https://routehive.eu/api/v1/stops \
  -H "Authorization: Bearer rh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "Budapest, Andrássy út 1.",
    "name": "Example Ltd.",
    "phone": "+36 30 123 4567",
    "reference": "WS-1001",
    "cod_amount": 12500,
    "packages": ["PKG-1001"]
  }'

Endpoints

GET /api/v1/routes?date=YYYY-MM-DD
Routes of a day (default: today, in the company time zone).
GET /api/v1/routes/{id}
A route with its stops, in order.
POST /api/v1/stops
A new stop, for example a web shop order.
GET /api/v1/stops/{id}
Status of a stop: delivered, failed, amount collected, photo and signature.

Adding a stop

Without a route, the stop goes to the day's Incoming route, and the dispatcher assigns it from there. If you send the same order number (reference) again for the same day, no new stop is created: you get the existing one back. Resending is safe.

Fields

address
The address (required). With coordinates, geocoding is skipped.
name
Name of the recipient or company.
phone, email
Phone number and email address for notifications.
reference
Your order number: you recognise the stop by it in webhooks, and it prevents duplicates.
cod_amount, payment_required
Cash on delivery in the smallest unit of the currency (forint: whole forint, euro: cents).
date
Day of the Incoming route (YYYY-MM-DD). Default: today.
route_id
A specific route instead of the Incoming one, if it can still take stops.
packages
Package barcodes: the driver scans them before delivery.
require_photo, require_signature
Required photo or signature for the delivery.

Webhooks

Set the webhook URL on the same page, https only, and choose which events to receive. Routehive sends a JSON POST for each event; the content is the same as the stop status response.

stop.delivered
A stop was delivered (with the amount collected and photo and signature flags).
stop.failed
A delivery failed (with the driver's note).
route.dispatched
A route was sent to the driver.
route.completed
A route was completed.
{
  "event": "stop.delivered",
  "event_id": "stop_..._delivered_20261120143005123",
  "created_at": "2026-11-20T14:30:05Z",
  "data": {
    "id": "...",
    "route_id": "...",
    "reference": "WS-1001",
    "status": "delivered",
    "delivered_at": "2026-11-20T14:30:04Z",
    "note": null,
    "payment_required": true,
    "paid": true,
    "cod_amount": 12500,
    "collected_amount": 12500,
    "has_photo": true,
    "has_signature": false
  }
}

Verifying the signature

Every request has an X-Routehive-Signature header: t=timestamp,v1=signature. The signature is the HMAC-SHA256 of the timestamp, a dot and the raw body, using the webhook secret. If it does not match, reject the request.

import { createHmac, timingSafeEqual } from "node:crypto";

// header: X-Routehive-Signature, body: the raw request body (string)
function verify(header, body, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return fresh && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}

Any 2xx response confirms the delivery. On errors we retry less and less often (1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, 24 hours). After 50 failures in a row, the webhook is turned off and the owner gets an email.

Errors and limits

Errors look like {"error": {"code": …, "message": …}}. The code is in English, the message in your company language. Each key can make 120 requests per minute; above that you get 429.

API and webhooks

Plan tomorrow morning's routes this way

Sign up, add your drivers, load your addresses. Free for 15 stops in total, in 2 routes, no credit card.