Developers
LiveWebhooks: signed commitment events.
Ordo can POST an event to your server when a commitment is proposed, confirmed, coming due, overdue, kept, renegotiated or broken. Each request is signed with your endpoint's secret so you can check it came from Ordo.
Add an endpoint
In the Ordo app, a workspace admin or manager opens Settings → Developers, adds the endpoint URL and picks the events it should receive (all of them by default). API keys cannot add or change endpoints, so a leaked key cannot redirect your events.
- The URL must be
https://and reachable on the public internet. Private, loopback and link-local addresses are refused, and so are credentials in the URL. - The signing secret starts with
whsec_and is shown once, at creation or when you rotate it. - Up to 10 endpoints per workspace.
- Send test delivers a signed
pingevent right away and shows what your endpoint answered. Test pings are not retried.
Events
| Event | Sent when |
|---|---|
commitment.proposed | A new proposal landed in the review queue. |
commitment.confirmed | A person (or an allowed key) confirmed a commitment. |
commitment.due_soon | A confirmed commitment is coming due. Sent once. |
commitment.overdue | A confirmed commitment passed its due date. Sent once. |
commitment.fulfilled | The commitment was marked fulfilled. |
commitment.renegotiated | The due date moved to a later one. |
commitment.broken | The commitment was marked broken or dropped. |
Every event carries the full commitment in data.commitment, in the same shape the API returns.
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: Ordo-Webhooks/1
Ordo-Event: commitment.confirmed
Ordo-Delivery: …
Ordo-Signature: t=1795017600,v1=5f2c…e9
{
"id": "…",
"type": "commitment.confirmed",
"createdAt": "2026-11-18T14:00:00.000Z",
"workspaceId": "…",
"data": {
"commitment": { "id": "…", "object": "commitment", "state": "confirmed", "title": "Send Acme the revised SOW", "…": "…" }
}
}Verify the signature
The Ordo-Signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of the string `${t}.${body}` keyed with your endpoint secret. To verify:
- Read the raw request body before any JSON parsing; re-serialised JSON will not match.
- Compute the HMAC over
t, a dot, and the raw body. - Compare it to
v1in constant time. - Reject timestamps far from your clock (five minutes is a sensible window) to stop replays.
import { createHmac, timingSafeEqual } from "node:crypto";
/** rawBody: the request body exactly as received, before JSON parsing. */
export function verifyOrdoSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(header ?? "").split(",").map((part) => part.trim().split("=")),
);
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const given = Buffer.from(parts.v1 ?? "", "utf8");
const wanted = Buffer.from(expected, "utf8");
return given.length === wanted.length && timingSafeEqual(given, wanted);
}import hashlib, hmac, time
def verify_ordo_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
t = int(parts.get("t", "0"))
if not t or abs(time.time() - t) > tolerance:
return False
signed = f"{t}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))t. Rotating the secret takes effect on the next attempt.Responding and retries
Answer with any 2xx within 10 seconds. Redirects are not followed and count as failures. Do slow work after you respond.
A failed delivery is retried 7 more times, waiting 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h between attempts: 8 attempts over about 45 hours. After the last one fails, Ordo turns the endpoint off and emails the person who created it. Fix the endpoint, then turn it back on in Settings → Developers. The delivery log there keeps 30 days of events.
Retries mean you can get the same event more than once. The body's id and the Ordo-Delivery header stay the same across retries, so use them to skip duplicates. Events can arrive out of order; compare the commitment's updatedAt if order matters.
API version 2026-11-17. Breaking changes are versioned; we email key holders before they ship. Request access.
