API & Webhooks

Everything you can do in the ORKSTRA UI you can do via the REST API. The API & Webhooks module is the integration backbone — for ERPs, accounting, BI tools, custom clients, and partner products.

Overview

The API is OpenAPI 3.1 documented, OAuth 2.0 protected, and rate-limited at the edge. Webhooks let your systems subscribe to events instead of polling.

Detailed API reference. The full OpenAPI reference lives at docs.orkstra.com/api (built with Mintlify). This module guide is the conceptual overview; the API reference is the canonical spec.

Screenshot: API tokens and webhook subscriptions screen

Key concepts

REST API. 854 endpoints today, growing. Versioned (/v1, /v2). All payloads JSON. All amounts as strings (decimal-safe).

OAuth 2.0. Three flows: client credentials (machine-to-machine), authorization code with PKCE (user-facing apps), refresh tokens.

API token. Long-lived machine credential. Tenant admins create and rotate.

Webhook subscription. A (event, callback URL, secret) triple. ORKSTRA POSTs to the URL on every matching event.

HMAC signature. Every webhook payload is signed with HMAC-SHA256 using the subscription secret.

Rate limits. Default: 600 requests / minute per token. Premium: 3,000 / minute. Burst: 50.

Idempotency. Mutating endpoints accept an Idempotency-Key header to make retries safe.

Step-by-step: create an API token

1. Admin → API → Tokens → New token.
2. Name it (e.g., Accounting sync).
3. Pick scopes (read-only, full, or fine-grained).
4. (Optional) Set expiry.
5. Click Create. Copy the token — it's shown once.

Step-by-step: subscribe to a webhook

1. Admin → API → Webhooks → New subscription.
2. Pick events (e.g., ipc.certified, vo.agreed, nce.created).
3. Enter callback URL (must be HTTPS).
4. Copy the generated secret.
5. ORKSTRA sends a test ping; if your endpoint responds 2xx, the subscription is active.

Step-by-step: verify a webhook signature

import hmac
import hashlib

def verify(payload_bytes, signature_header, secret):
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

The signature is sent in the X-Orkstra-Signature header. Reject any request whose signature doesn't verify.

Common tasks

• Retry on failure: ORKSTRA retries failed webhook deliveries with exponential backoff for 24 hours.
• Replay a delivery: Admin → API → Webhooks → Deliveries → Replay.
• Rotate a token: Admin → API → Tokens → [token] → Rotate.
• List all events: Admin → API → Events lists every event type with sample payloads.

Troubleshooting

• "401 on every request." — Token invalid or expired. Verify token, check expiry.
• "429 rate limited." — Slow down or upgrade plan. The Retry-After header tells you when to retry.
• "Webhook signature fails." — Common cause is parsing the body before verifying. Verify against the raw bytes.
• "Webhook receives duplicates." — Retries — use the X-Orkstra-Event-Id header to dedupe.

Limits & policies

• Max API key per tenant: 50.
• Max webhook subscriptions per tenant: 100.
• Webhook payload max: 1 MB.
• Webhook timeout: 10 seconds.
• TLS: 1.2+ required.

Permissions reference

Permission	Who needs it
API_TOKEN_MANAGE	Tenant admin
WEBHOOK_MANAGE	Tenant admin
API_DELIVERY_LOG_VIEW	Tenant admin

See also: Developer guide, Admin overview, DMS.