Build OrganMatch into your stack

Authentication

Every request carries an organisation API key as a bearer token. Keys are created by an organisation owner or admin in the Enterprise console. The secret is shown once at creation; we store a SHA-256 hash of it plus the first few characters as a display prefix, so the secret itself cannot be recovered — if it is lost, revoke the key and create another.

curl https://api.organthis.com/api/v1/public/runs \
  -H "Authorization: Bearer om_live_…"

Scopes

Keys are least-privilege and read-only. A request for an endpoint outside the key's scopes returns 403; a missing, unknown or revoked key returns 401.

Endpoints

All responses are JSON and wrap the result in a data key. Runs are scoped to the organisation the key belongs to — a key can never read another tenant's data.

{
  "data": [
    {
      "id": "clx8f2n0a0001",
      "runNumber": 42,
      "status": "COMPLETED",
      "outcomeStatus": "SUCCESS",
      "viabilityPct": 78,
      "createdAt": "2026-08-20T08:00:00.000Z",
      "completedAt": "2026-08-27T09:14:00.000Z",
      "protocol": {
        "slug": "intestinal-organoid-v3",
        "title": "Intestinal organoid expansion",
        "organType": "INTESTINE"
      }
    }
  ]
}

Webhooks

Register an HTTPS endpoint in the console and subscribe it to the events you care about. Each endpoint gets its own signing secret. Every event is delivered as a POST with a versioned envelope; the event-specific fields live under data.

{
  "id": "5e9c1b0e-4b2a-4c3d-9f1a-6d8e2b7c0a11",
  "type": "run.completed",
  "version": "v1",
  "createdAt": "2026-08-27T09:14:02.113Z",
  "data": { }
}

Headers

Verifying a signature

The signature is an HMAC-SHA256 of {timestamp}.{raw body} keyed with the endpoint's signing secret. Compare it in constant time, and reject the request if it does not match — a valid signature is the only proof the request came from us.

import { createHmac, timingSafeEqual } from 'crypto';

// body must be the RAW request body, before any JSON parsing.
export function verify(body, headers, signingSecret) {
  const timestamp = headers['x-om-timestamp'];
  const received  = String(headers['x-om-signature'] || '').replace(/^sha256=/, '');

  // Reject replays. The delivery attempt itself times out after 10s.
  const ageMs = Date.now() - Number(timestamp);
  if (!timestamp || Number.isNaN(ageMs) || Math.abs(ageMs) > 5 * 60 * 1000) return false;

  const expected = createHmac('sha256', signingSecret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(received, 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Delivery and retries

• Any 2xx counts as accepted.
• Each attempt times out after 10 seconds — acknowledge fast and do your work afterwards.
• Up to 6 attempts with exponential backoff, then the delivery is dead-lettered and stays visible in the console.
• Retries reuse the same X-OM-Event-Id, so deduplicate on it.
• Two failures are terminal and are not retried at all: the endpoint being deactivated, and its URL failing the address check on a later attempt. Both dead-letter immediately on the first attempt that sees them.
• Redirects are not followed. A 3xx is recorded as a failed attempt — register the final URL directly.

Endpoint URL rules

Endpoints are checked when you register them and again before every delivery attempt, with the hostname re-resolved each time. A URL is refused if it:

• is not https, or uses a port other than 443
• contains a username or password
• resolves to a private, loopback, link-local or otherwise non-public address

These checks reduce, but cannot completely eliminate, the window between a DNS lookup and the connection that follows it. We do not treat your endpoint as a trusted network location.

Event catalogue

Envelope version v1. Fields may be added to data without a version bump, so parse permissively and ignore what you do not recognise. New event types are added over time — route on type and ignore what you have not subscribed to.

{
  "experimentId": "clx8f2n0a0001",
  "runNumber": 42,
  "protocol": { "slug": "intestinal-organoid-v3", "title": "Intestinal organoid expansion" }
}

{
  "experimentId": "clx8f2n0a0001",
  "runNumber": 42
}

{
  "experimentId": "clx8f2n0a0001",
  "outcomeStatus": "SUCCESS",
  "viabilityPct": 78
}

{
  "experimentId": "clx8f2n0a0001",
  "runNumber": 42,
  "deviationId": "clx8f2n0a0003",
  "code": "REAGENT_LOT",
  "phaseNumber": 2
}

{
  "message": "This is a test event from OrganMatch. No run or outcome was created.",
  "endpointId": "clx8f2n0a0002",
  "triggeredBy": "you@lab.org"
}

Errors and limits

Errors use standard status codes with a JSON body carrying a message — except 429, which returns { type, title, status, detail }.