ZahlenwerkDocs

Webhooks

Notify your own systems automatically about new reports, documents and positions.

Webhooks send an HTTP request to your own system when certain events happen, for example to a data warehouse or an automation tool.

Owners and Team Admins can set them up, under SettingsIntegrationsWebhooksConfigure: enter the Endpoint URL and Description (optional), then click Add webhook.

Zahlenwerk then shows the signing secret (starts with whsec_) once. Copy it into your system right away.

Events

EventWhen
report.parsedA report was read successfully.
report.failedReading a report failed.
document.extractedA capital call notice or capital account statement was read, including a re-read.
position.createdA position was created, in the app, in chat or through an AI client.

Under Events you choose which events a webhook receives. Choose none and it receives all of them, including ones added later.

Request body

The body is JSON. The Zahlenwerk-Event header names the event.

{
  "event": "report.parsed",
  "occurred_at": "2026-10-08T09:30:00.000Z",
  "organization_id": "…",
  "data": {
    "report_id": "…",
    "collection_id": "…",
    "collection_name": "…",
    "resource": "zahlenwerk://report/…"
  }
}

data per event:

EventFields in data
report.parsedreport_id, collection_id, collection_name, resource
report.failedreport_id, collection_id, collection_name, error (readable reason, at most 500 characters), resource
document.extracteddocument_id, document_type, position_id, position_ids (one statement can cover several positions)
position.createdposition_id, instrument_type, name

Verify the signature

Every request carries the header:

Zahlenwerk-Signature: t=<unix-time>,v1=<signature>

v1 is an HMAC-SHA256 over "<t>.<body>", keyed with your webhook's secret. Verify the signature and reject requests older than five minutes.

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

export function verify(header: string, body: string, secret: string) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${body}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const given = Buffer.from(parts.v1 ?? '');
  return fresh && given.length === expected.length && timingSafeEqual(Buffer.from(expected), given);
}

Delivery

  • Any response other than 2xx counts as a failure, 4xx included.
  • If your system doesn't respond within 10 seconds, the delivery counts as failed.
  • Redirects (3xx) are not followed and count as failures.
  • Zahlenwerk retries failed deliveries up to four times, with growing intervals. Your system should tolerate duplicate requests.

Requirements

  • HTTPS endpoints only.
  • Internal and private addresses are rejected.

There is no general REST API. For read and write access, use the MCP endpoint.

On this page

Log in
EN
EnglishDeutschEspañol