Webhooks
Notify your own systems automatically about new reports 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 an optional Description, 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 document was read. |
position.created | A position was created. |
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);
}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.