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
| Event | When |
|---|---|
report.parsed | A report was read successfully. |
report.failed | Reading a report failed. |
document.extracted | A capital call notice or capital account statement was read, including a re-read. |
position.created | A 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:
| Event | Fields in data |
|---|---|
report.parsed | report_id, collection_id, collection_name, resource |
report.failed | report_id, collection_id, collection_name, error (readable reason, at most 500 characters), resource |
document.extracted | document_id, document_type, position_id, position_ids (one statement can cover several positions) |
position.created | position_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.