Setting up Routewren for a new depot
Depot Setup › Tech guide
Tech guide
Setting up Routewren for a new depot

IT and operations staff at a delivery firm who set up a new depot in the Routewren Console

Version 1.0 · 6 Nov 2026 · Before you start · Create the depot · Set the depot rules · Create an API key · Connect a webhook · Check the setup

Feature Depot Setup Version 1.0 Date 6 Nov 2026 Owner Routewren Docs Language English · Original

A depot is a place where your vans start and finish the day. Routewren needs one depot for each. This guide sets up the depot, its rules, an API key and a webhook, in that order.

  • 4 parts to set up: the depot, its rules, an API key and a webhook.
  • 1 code that never changes: the depot code, for example nth-depot-01.
  • Test first: make the key and the webhook in Test mode, then repeat them in Live.

1. Before you start

Console › Depots

1.1 What you need

You need Example Note
A Console login your work e-mail, mei@example.com Ask your admin for a login
The depot name Northside Depot Shown on the map and in reports
The depot code nth-depot-01 The API and the driver login use it
The time zone Asia/Kuala_Lumpur Picked from a list
The street address 12 Dock Lane, Northside Industrial Park Routewren finds the map pin from it
A server address for webhooks https://orders.example.com/hooks/routewren Must start with https
Required

The code uses lowercase letters, digits and hyphens, up to 24 characters. Routewren uses it in the API and in the driver login. A wrong code means a new depot, so check it twice.

The Console has a Live and a Test switch at the top right. Test has fake vans and sends nothing real, and an amber strip shows under the top bar. A depot exists in both modes, but the keys are different. Make your keys and webhooks in Test first.

2. Create the depot

Console › Depots › Add depot

2.1 Fill in the form

  1. Click Depots in the left menu.

  2. Click Add depot at the top right.

    Click Add depot
    Click Add depot

  3. Type the depot name, Northside Depot.

  4. Type the depot code, nth-depot-01. A green tick means the code is free.

  5. Pick the time zone, Asia/Kuala_Lumpur.

  6. Open Copy rules from and pick Harbour Road Depot. This is optional. It saves time.

    Name, code, time zone and the optional copy
    Name, code, time zone and the optional copy

2.2 Set the address and create

  1. Type the street address.

  2. Look at the map pin. Drag it if it is in the wrong place.

  3. Click Create depot. The depot opens on its Rules page.

    Address, map pin and Create depot
    Address, map pin and Create depot

3. Set the depot rules

Depots › Northside Depot › Rules

3.1 The geofence radius

The geofence radius decides when a van counts as arrived. The default is 150 m. It suits most depots.

  1. Type the radius in the first box. Use a number from 50 to 500.

    Type the radius, for example 150
    Type the radius, for example 150

A smaller radius is more exact, but in a city street a GPS jump can miss the stop. A larger radius misses less, but a van can count as arrived while it is still a street away.

3.2 Pings, hours and alerts

Setting Default Allowed What it does
Geofence radius 150 m 50 to 500 m How close a van must be to a stop to count as arrived
Ping while moving 10 sec 5 to 60 sec How often a moving van reports
Ping while parked 60 sec 30 to 300 sec How often a parked van reports
Working hours 06:00 to 20:00 any No alerts outside these hours
Late alert after 15 min any The dispatcher gets a red flag when a stop is this late
History kept 90 days 30 to 365 days After this the location history is deleted for good

  1. Set While moving in the Location pings card.

  2. Set While parked in the same card.

    The two ping intervals
    The two ping intervals

  3. Set the working hours Start.

  4. Set the working hours End. Tick the days.

  5. Set Late alert after.

  6. Set History kept.

    Working hours, late alert and history
    Working hours, late alert and history

3.3 Save the rules

Nothing is saved until you click Save changes. If you leave the page first, the changes are lost.

  1. Click Save changes in the bar at the bottom.

4. Create an API key

Depots › Northside Depot › API keys

4.1 Make the key

Make the first key in Test mode. A key works for one depot and one mode.

  1. Type a name for the key, nth-depot-01 dispatch.

  2. Choose Test.

  3. Tick the scopes the key needs. Give a key only what it needs.

  4. Click Create key.

    Name, mode, scopes and Create key
    Name, mode, scopes and Create key
Scope What the key can do Give it to
pings:write Send location pings The driver app and GPS trackers
routes:read Read routes and stops Your dashboards and reports
webhooks:manage Add and remove webhook endpoints Your own set-up scripts only

4.2 Copy the key

Routewren shows the key one time. It keeps only a hash. If you lose the key, revoke it and make a new one.

  1. Click Copy.

  2. Paste the key into your team's secret store.

  3. Click I have copied the key.

    The key is shown once
    The key is shown once

A Test key starts with rw_test_ and a Live key starts with rw_live_.

4.3 Use the key

Send the key in the Authorization header. The API address is https://api.example.com/v1.

curl https://api.example.com/v1/routes \
  -H "Authorization: Bearer <api_key>"
Answer Meaning What to do
401 The key is wrong or revoked Check the key and the mode
403 The key has no scope for this call Make a key with the scope
422 A ping is not valid Check the fields of the ping
429 More than 600 requests a minute for this key Wait for the time in the Retry-After header

To replace a key: make the new one, switch your system to it, wait 24 hours, then click Revoke on the old key.

5. Connect a webhook

Depots › Northside Depot › Webhooks

5.1 Add the endpoint

  1. Click Add endpoint.

  2. Type the address of your server. It must start with https. For example https://orders.example.com/hooks/routewren.

  3. Tick the events you want, then click Save. Routewren shows the signing secret one time. Copy it into your secret store.

Event When it is sent
stop.arrived A van is inside the geofence of its next stop
stop.delivered The driver taps Delivered
route.completed The last stop of a route is done
driver.offline A driver has sent no pings for a while

5.2 Check the signature

Every call has a Routewren-Signature header. Your server checks it before it trusts the call.

Routewren-Signature: t=<timestamp>,v1=<signature>

signed    = "<timestamp>.<body>"
expected  = HMAC-SHA256(<signing_secret>, signed)
accept    = expected equals <signature>, and <timestamp> is under 5 minutes old

Answer with a 2xx code within 5 seconds. A slow answer counts as a failure.

5.3 Send a test event

  1. Click Send test event on the endpoint. Routewren sends a fake stop.arrived.

    Click Send test event
    Click Send test event

  2. Open the delivery log and look for the code 200.

    A 200 in the delivery log
    A 200 in the delivery log

If your server fails, Routewren tries again 6 times and then marks the endpoint Failing. The same event can arrive twice: use its id to ignore a copy.

6. Check the setup

Depots › Northside Depot

  • The depot code is right, and the pin is on the depot.
  • The rules are saved. Reload the page and look.
  • A Test key exists with only the scopes it needs, and it is in your secret store.
  • Your server answers the test event with a 200.
  • The same steps are done again for Live keys and Live webhooks.

Change log

Version Date Change By
1.0 2026-11-06 First version Routewren Docs