Skip to content
DevelopersGet an API key

Webhooks

Instead of asking Harlo every few minutes what's new, give it an address and it tells you the moment something happens.

Set one up

  1. In Harlo, open Settings, API keys and under Webhooks choose Add endpoint.
  2. Paste the address that should receive events: a Zapier Catch Hook URL, a Make Custom webhook URL, or your own server. It must be a public https:// address on the standard port.
  3. Pick the events you want, then copy the signing secret (whsec_…). It's shown once.
  4. Choose Send test. A ping event arrives, and the result shows under Deliveries.

Events

typeWhendata.object
load.createdA load was created.Load
load.status_changedA load's status changed (booked, dispatched, in transit, delivered...).Load
load.deliveredA load was delivered.Load
invoice.createdAn invoice was issued.Invoice
invoice.paidAn invoice was paid in full.Invoice
invoice.voidedAn invoice was voided.Invoice
payment.createdA payment was recorded.Payment
customer.createdA customer was added.Customer
driver.createdA driver was added.Driver
equipment.createdA truck or trailer was added.Equipment
document.createdA document was attached (not identity, medical or bank documents).Document

What arrives

A POST with a JSON body. data.object is the record exactly as the API returns it, read when the event is sent, so it reflects the change that caused it.

POST to your endpoint
{
  "id": "5f0c2a9e-7d1b-4c3e-9a51-2b8f6d4e7a10",
  "object": "event",
  "type": "invoice.paid",
  "created_at": "2026-11-14T15:42:56.089893+00:00",
  "api_version": "2026-11-14",
  "data": {
    "object": {
      "id": "a3b858d0-046b-4ded-8f6f-a5a4a5837114",
      "object": "invoice",
      "number": "INV-L-00001",
      "status": "paid",
      "…": "the full invoice, as GET /v1/invoices/{id} returns it"
    }
  }
}
Harlo-Event-TypeThe event's type.
Harlo-Event-IdThe event's id.
Harlo-Webhook-IdWhich of your endpoints this is.
Harlo-Delivery-Attempt1 the first time, then 2, 3... on retries.
Harlo-Signaturet=<unix seconds>,v1=<signature>, explained below.

Check it came from Harlo

v1is the hex HMAC-SHA256 of the timestamp, a dot, and the raw request body, keyed with your endpoint's signing secret. Compute it yourself and compare in constant time. Reject timestamps more than five minutes old, so a captured request can't be replayed later.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.HARLO_WEBHOOK_SECRET;   // whsec_…

// Verify against the raw body: re-serialising the JSON changes the bytes.
app.post("/harlo", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("Harlo-Signature") ?? "";
  const t = /t=(\d+)/.exec(header)?.[1];
  const v1 = /v1=([0-9a-f]+)/.exec(header)?.[1];
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  if (!t || !v1 || !fresh || !crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
    return res.status(400).send("bad signature");
  }
  const event = JSON.parse(req.body);
  res.sendStatus(200);          // answer first, then do the work
  handle(event);                // your code; ignore event.id values you've seen
});

Zapier and Make

They can't check signatures, and don't need to: their hook URLs are long and secret. Keep the URL private and make a new endpoint if it leaks.

Retries

  • Answer with any 2xx within 10 seconds. Do slow work after you answer.
  • Anything else (an error status, a timeout, a redirect) is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours: eight tries over about two days. Redirects are never followed; give the final address.
  • An event can arrive more than once, and occasionally out of order. Use the event idto ignore repeats, and the object's updated_at to keep the newest.
  • After 25 failed tries in a row, Harlo turns the endpoint off and says why in Settings. Fix it, turn it back on, and use Send again on the deliveries you missed.
  • Events and their delivery history are kept for 30 days.

Keep the secret safe

Treat whsec_… like a password. If it leaks, choose New secret on the endpoint: the old one stops working at once, so update your server straight away.

NextSpreadsheets and CSV