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
- In Harlo, open Settings, API keys and under Webhooks choose Add endpoint.
- 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. - Pick the events you want, then copy the signing secret (
whsec_…). It's shown once. - Choose Send test. A
pingevent arrives, and the result shows under Deliveries.
Events
| type | When | data.object |
|---|---|---|
load.created | A load was created. | Load |
load.status_changed | A load's status changed (booked, dispatched, in transit, delivered...). | Load |
load.delivered | A load was delivered. | Load |
invoice.created | An invoice was issued. | Invoice |
invoice.paid | An invoice was paid in full. | Invoice |
invoice.voided | An invoice was voided. | Invoice |
payment.created | A payment was recorded. | Payment |
customer.created | A customer was added. | Customer |
driver.created | A driver was added. | Driver |
equipment.created | A truck or trailer was added. | Equipment |
document.created | A 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-Type | The event's type. |
Harlo-Event-Id | The event's id. |
Harlo-Webhook-Id | Which of your endpoints this is. |
Harlo-Delivery-Attempt | 1 the first time, then 2, 3... on retries. |
Harlo-Signature | t=<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
2xxwithin 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'supdated_atto 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.