Build on YarnTally

Authentication

Generate an API key from Admin → API access (the same list of endpoints appears there). Every request needs an Authorization: Bearer YOUR_KEY header.

curl https://yarntally.mnbresearch.com/api/v1/inventory \
  -H "Authorization: Bearer yt_xxxxxxxx_..." \
  -H "Content-Type: application/json"

The REST API is part of the Business plan. Rate limits: 1,200 req/min on Business, 6,000 req/min on Enterprise.

Endpoints available now

Five read endpoints. Everything is scoped to the org that owns the API key, and all of it is read-only — nothing in v1 writes to your data.

Not built yetPlanned endpoints

These do not exist. Every one of them returns 404 today. They are listed so you know what is coming — do not write integration code against them, and email us if one of them is what you need next.

WebhooksLive

Add an endpoint under Admin → API access → Webhooks, pick the events you want, and copy the signing secret — it is shown once, at creation. We POST JSON to your URL (https only) as things happen.

What a delivery looks like

The body is an envelope; data varies by event and carries the record itself. Treat unknown fields as additive — we will add fields, and will not remove or rename them without a new event name.

POST /your/endpoint
Content-Type: application/json
X-YarnTally-Event: sale.created
X-YarnTally-Timestamp: 1790000000
X-YarnTally-Delivery: 6f1c…  (id of this attempt, quote it in support mail)
X-YarnTally-Signature: 9ad3…  (hex HMAC-SHA256)

{
  "event": "sale.created",
  "occurred_at": "2026-09-24T09:14:02.881Z",
  "org_id": "…",
  "data": { "sale": { "id": "…", "invoice_no": "INV-000412", "total": 184500.00, … } }
}

Verifying the signature

Sign the timestamp, a dot, then the raw body — the bytes exactly as you received them, before any JSON parsing. The timestamp is inside the signed material so a captured delivery cannot be replayed at your endpoint forever.

// Verify a YarnTally webhook (Node.js)
import crypto from "crypto";

const SECRET = process.env.YARNTALLY_WEBHOOK_SECRET; // shown once, at creation

export function verify(rawBody, headers) {
  const signature = headers["x-yarntally-signature"];
  const timestamp = headers["x-yarntally-timestamp"]; // unix seconds
  if (!signature || !timestamp) return false;

  // Reject replays. We re-send the ORIGINAL timestamp on retries, so allow
  // 300 seconds.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  // Sign the timestamp, a dot, then the raw body — bytes exactly as received,
  // before any JSON parsing or re-serialising.
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Retries, ordering and the small print

• Success is any 2xx. Reply quickly and do your work afterwards — we give up on a response after 8 seconds and treat that as a failure.
• Retries happen once a day, up to 5 attempts in total, and an admin can retry immediately from the Webhooks screen. Every attempt — status, response body, attempt number — is listed there, so a delivery that stopped working is visible rather than silent.
• Be idempotent. A retry re-sends the original payload with a new timestamp and signature. Deduplicate on X-YarnTally-Delivery.
• An endpoint that fails 20 times in a row is switched off and has to be re-enabled from the Webhooks screen. We will not post into a void indefinitely.
• No ordering guarantee. Deliveries are independent; use occurred_at if sequence matters.
• Bulk imports do not fire per-row events. Importing 400 customers from a spreadsheet emits nothing — deliberately, because 400 POSTs from one click is an outage at your end, not an integration. Re-read the API after a bulk import.