How to Build Your Own Uber Eats on the Hawky API

A weekend-scale walkthrough for building an Uber-Eats-style delivery app on top of Hawky.

What Hawky gives you for free

• Devices + drivers: your courier with a phone or a GPS tracker. Hawky already handles real-time position, speed, status, and alerts.
• Tasks (/tasks): a single delivery — drop-off, customer, assignment, status.
• Geofences: pickup zones (restaurants) and delivery zones (neighborhoods / buildings).
• Share links: public URLs so the customer tracks their order without signing up.
• Webhooks: geofence enter/exit, SOS, ignition-off fire automatic callbacks to your backend.

The minimum viable flow

1. Customer places an order in your app
   → hawky_add_task { address, lat, lng, customer_name, customer_phone }

2. Auto-assignment (your algorithm)
   → hawky_get_drivers online + hawky_get_devices_latest
   → compute distance to pickup
   → hawky_assign_task to the nearest driver

3. Driver accepts
   → hawky_update_task_status status="on_the_way"
   → hawky_create_share { device_id, expire_at: +2h }
   → SMS the link to the customer

4. Driver arrives (geofence fires event)
   → hawky_update_task_status status="arrived"
   → push to customer

5. Delivery confirmed
   → hawky_update_task_status status="delivered" + note with proof photo URL

ETA, proof of delivery, anti-fraud

Compute ETA yourself: distance-to-drop-off divided by driver's historical avg speed (from hawky_get_device_history, past 7 days). For proof of delivery, Hawky stores metadata but photos/signatures live in your own S3/R2 bucket — put the URL in the task note.

Three anti-fraud rules to ship from day one:

1. If the "delivered" point is > 50 m from the task's lat,lng, require a supervisor override.
2. If status is delivered but device speed != 0 for 60 seconds, flag as suspicious.
3. Orders outside operating hours auto-cancel.

Real costs

Personal plan is $90 MXN/mo per unit (≈ $6 USD; driver brings their device or uses their phone). 100 couriers ≈ $520 USD/mo. Add your own mobile data if the device isn't a smartphone.

What you DON'T need to build

• Real-time position broadcast (done)
• Geofence evaluation (edge-evaluated per ping)
• SOS / ignition / harsh-driving alerts (built in)
• Historical route reconstruction (hawky_get_device_history)

Reference architecture

How the pieces wire up for a 100–200 orders/day MVP:

┌───────────────┐      POST /api/tasks       ┌───────────────┐
│ Customer app  │ ─────────────────────────▶ │   Hawky API   │
│               │                            │ (GPS + tasks) │
└──────┬────────┘ ◀──── share URL ────────── └──────┬────────┘
       │                                             │ webhook
       ▼                                             ▼
┌───────────────┐   geofence_in / delivered   ┌───────────────┐
│ Your backend  │ ◀────────────────────────── │   Webhook     │
│ (Node/Python) │                             │   (signed)    │
└───────────────┘                             └───────────────┘

Your backend stays thin: it receives orders, converts them into Hawky tasks, and listens for event webhooks to update state in your DB.

Real code — nearest-courier auto-assignment

// Node.js with native fetch
async function assignNearestCourier(taskId, pickupLat, pickupLng) {
  const drivers = await hawky.get("/get_drivers", { status: "online" });
  const devices = await hawky.get("/get_devices_latest");
  const deviceById = Object.fromEntries(devices.items.map(d => [d.id, d]));

  const ranked = drivers
    .filter(d => d.device_id && deviceById[d.device_id])
    .map(d => {
      const dev = deviceById[d.device_id];
      const dist = haversine(pickupLat, pickupLng, dev.lat, dev.lng);
      return { driver: d, distance_m: dist };
    })
    .sort((a, b) => a.distance_m - b.distance_m);

  const winner = ranked.find(r => r.distance_m < 3000); // 3 km cap
  if (!winner) throw new Error("NO_COURIER_AVAILABLE");

  await hawky.post("/tasks/" + taskId + "/assign", { driver_id: winner.driver.id });
  return winner;
}

Real costs — breakdown for 100 active couriers

Item	MXN / mo	Notes
100 × Personal plan	$9,000	Each courier brings their phone
Mobile data (optional)	$0 – $15,000	Only if you provide SIMs
Backend hosting (CF Workers + D1)	~$0 – $150	Free under 100K req/day
SMS gateway (optional)	$500 – $2,000	Customer notifications
Payment fees (if applicable)	3% - 4% GMV	Stripe / MercadoPago / Clip

80% of operating cost is typically the couriers themselves (pay-per-delivery), not infrastructure.

FAQ

Does Hawky provide the couriers?

No. Hawky is the tracking + dispatch layer. You hire the drivers — W-2, 1099, or gig contracts. Many customers use Hawky's mobile app as their driver-facing app.

How do I pay couriers?

Outside of Hawky. Use Stripe Connect, Dwolla, or direct transfer. Hawky reports completed tasks per driver, which you use as input for payouts.

Can I scale to 1,000 couriers?

Yes — the Enterprise plan has higher rate limits and master accounts. Email hello@hawky.tech with projected volume.

Next step

Install the Hawky MCP in Claude Code or Cursor and try creating your first delivery task with natural language. Or browse the full API reference.