Webhooks

import { randomUUID } from 'node:crypto';
import { LiquidityOsClient } from '@klineo/liquidity-os-sdk';

const client = new LiquidityOsClient({
  baseUrl: process.env.KLINEO_API_BASE_URL!,
  organizationId: process.env.KLINEO_ORGANIZATION_ID!,
  accessToken: process.env.KLINEO_ACCESS_TOKEN!,
});

// Persist this key before the request; reuse it if the response is lost.
const intentKey = `webhook:${randomUUID()}`;
const created = await client.createWebhooks({
  idempotencyKey: intentKey,
  body: {
    url: 'https://your-public-domain.example/webhooks/klineo',
    eventTypes: [
      'record.simulation_study.completed',
      'record.proposal_workspace.validated',
    ],
    reason: 'Notify our integration when study and proposal records change.',
  },
});

// Write this value directly to your secret manager; never log it.
const signingSecret = created.data.signingSecret;
const subscription = created.data.subscription;

{
  "schemaVersion": "klineo-token-liquidity-os-webhook-v1",
  "eventType": "record.simulation_study.completed",
  "occurredAt": "2026-09-30T09:00:00.000Z",
  "data": {}
}

HMAC-SHA256(signingSecret, timestamp + "." + deliveryId + "." + rawBody)

import assert from 'node:assert/strict';
import { createHmac, timingSafeEqual } from 'node:crypto';

type WebhookHeaders = {
  deliveryId: string;
  timestamp: string;
  signature: string;
  eventType: string;
};

export function verifyWebhook(
  rawBody: Buffer,
  headers: WebhookHeaders,
  secret: string,
  maxAgeSeconds: number,
  nowMs = Date.now(),
): Record<string, unknown> {
  if (!/^whd_[0-9a-f]{32}$/u.test(headers.deliveryId)
    || !/^v1=[0-9a-f]{64}$/u.test(headers.signature)
    || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})$/u.test(headers.timestamp)) {
    throw new Error('Invalid webhook headers');
  }
  if (!secret.startsWith('whsec_') || !Number.isFinite(maxAgeSeconds)
    || maxAgeSeconds <= 0 || !Number.isFinite(nowMs)) {
    throw new Error('Invalid receiver configuration');
  }
  const expected = createHmac('sha256', secret)
    .update(`${headers.timestamp}.${headers.deliveryId}.`, 'utf8')
    .update(rawBody)
    .digest();
  const received = Buffer.from(headers.signature.slice(3), 'hex');
  if (!timingSafeEqual(expected, received)) throw new Error('Invalid signature');
  const signedMs = Date.parse(headers.timestamp);
  if (!Number.isFinite(signedMs) || signedMs > nowMs + 60_000
    || nowMs - signedMs > maxAgeSeconds * 1000) {
    throw new Error('Timestamp outside receiver acceptance window');
  }
  const payload: unknown = JSON.parse(rawBody.toString('utf8'));
  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
    throw new Error('Invalid webhook body');
  }
  const event = payload as Record<string, unknown>;
  if (event.schemaVersion !== 'klineo-token-liquidity-os-webhook-v1'
    || event.eventType !== headers.eventType
    || typeof event.occurredAt !== 'string'
    || Date.parse(event.occurredAt) !== signedMs
    || !event.data || typeof event.data !== 'object' || Array.isArray(event.data)) {
    throw new Error('Invalid webhook envelope');
  }
  return event;
}

const secret = 'whsec_local-example-only';
const headers: WebhookHeaders = {
  deliveryId: `whd_${'a'.repeat(32)}`,
  timestamp: '2026-09-30T09:00:00.000Z',
  signature: '',
  eventType: 'record.simulation_study.completed',
};
const body = Buffer.from(JSON.stringify({
  schemaVersion: 'klineo-token-liquidity-os-webhook-v1',
  eventType: headers.eventType,
  occurredAt: headers.timestamp,
  data: {},
}));
headers.signature = 'v1=' + createHmac('sha256', secret)
  .update(`${headers.timestamp}.${headers.deliveryId}.`)
  .update(body).digest('hex');
const now = Date.parse(headers.timestamp);
assert.equal(verifyWebhook(body, headers, secret, 86400, now).eventType, headers.eventType);
assert.throws(() => verifyWebhook(Buffer.concat([body, Buffer.from(' ')]), headers, secret, 86400, now));
assert.throws(() => verifyWebhook(body, headers, secret, 86400, now + 86401_000));
assert.throws(() => verifyWebhook(body, { ...headers, eventType: 'tampered.event' }, secret, 86400, now));
console.log('Signature, body, event and age checks passed');

import hashlib
import hmac
import json
import math
import re
from datetime import datetime, timezone
from typing import Mapping


def verify_webhook(raw_body: bytes, headers: Mapping[str, str], secret: str,
                   max_age_seconds: float, now: datetime | None = None) -> dict:
    delivery_id = headers["deliveryId"]
    timestamp = headers["timestamp"]
    signature = headers["signature"]
    if (not re.fullmatch(r"whd_[0-9a-f]{32}", delivery_id)
            or not re.fullmatch(r"v1=[0-9a-f]{64}", signature)
            or not re.fullmatch(
                r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})",
                timestamp)):
        raise ValueError("Invalid webhook headers")
    if (not secret.startswith("whsec_") or not math.isfinite(max_age_seconds)
            or max_age_seconds <= 0):
        raise ValueError("Invalid receiver configuration")
    message = f"{timestamp}.{delivery_id}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), message, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature[3:]):
        raise ValueError("Invalid signature")
    signed_at = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
    current = now if now is not None else datetime.now(timezone.utc)
    age = (current - signed_at).total_seconds()
    if age < -60 or age > max_age_seconds:
        raise ValueError("Timestamp outside receiver acceptance window")
    event = json.loads(raw_body)
    if (not isinstance(event, dict)
            or event.get("schemaVersion") != "klineo-token-liquidity-os-webhook-v1"
            or event.get("eventType") != headers["eventType"]
            or not isinstance(event.get("occurredAt"), str)
            or datetime.fromisoformat(event["occurredAt"].replace("Z", "+00:00")) != signed_at
            or not isinstance(event.get("data"), dict)):
        raise ValueError("Invalid webhook envelope")
    return event


if __name__ == "__main__":
    secret = "whsec_local-example-only"
    headers = {
        "deliveryId": "whd_" + "a" * 32,
        "timestamp": "2026-09-30T09:00:00.000Z",
        "eventType": "record.simulation_study.completed",
    }
    body = json.dumps({
        "schemaVersion": "klineo-token-liquidity-os-webhook-v1",
        "eventType": headers["eventType"],
        "occurredAt": headers["timestamp"],
        "data": {},
    }, separators=(",", ":")).encode("utf-8")
    message = f'{headers["timestamp"]}.{headers["deliveryId"]}.'.encode() + body
    headers["signature"] = "v1=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    now = datetime.fromisoformat(headers["timestamp"].replace("Z", "+00:00"))
    assert verify_webhook(body, headers, secret, 86400, now)["eventType"] == headers["eventType"]
    for candidate, changed_headers, changed_now in [
        (body + b" ", headers, now),
        (body, headers, datetime(2026, 10, 1, 9, 0, 1, tzinfo=timezone.utc)),
        (body, {**headers, "eventType": "tampered.event"}, now),
    ]:
        try:
            verify_webhook(candidate, changed_headers, secret, 86400, changed_now)
        except ValueError:
            pass
        else:
            raise AssertionError("Invalid delivery was accepted")
    print("Signature, body, event and age checks passed")