Webhooks
Eigene Systeme bei neuen Berichten, Dokumenten und Positionen automatisch benachrichtigen.
Webhooks senden bei bestimmten Ereignissen eine HTTP-Anfrage an Ihr eigenes System, etwa an ein Data Warehouse oder ein Automatisierungswerkzeug.
Einrichten dürfen Inhaber und Team-Admins, unter EinstellungenIntegrationenWebhooksEinrichten: Endpunkt-URL und Beschreibung (optional) eintragen, Webhook hinzufügen.
Danach zeigt Zahlenwerk das Signaturgeheimnis (beginnt mit whsec_) einmalig an. Kopieren Sie es sofort in Ihr System.
Ereignisse
| Ereignis | Wann |
|---|---|
report.parsed | Ein Bericht wurde erfolgreich ausgelesen. |
report.failed | Das Auslesen eines Berichts ist fehlgeschlagen. |
document.extracted | Ein Kapitalabruf oder Kapitalkontoauszug wurde ausgelesen, auch erneut. |
position.created | Eine Position wurde angelegt, in der App, im Chat oder über einen KI-Client. |
Unter Ereignisse wählen Sie, welche Ereignisse ein Webhook erhält. Wählen Sie keines, erhält er alle, auch später hinzugefügte.
Inhalt einer Anfrage
Der Body ist JSON. Der Header Zahlenwerk-Event nennt das Ereignis.
{
"event": "report.parsed",
"occurred_at": "2026-10-08T09:30:00.000Z",
"organization_id": "…",
"data": {
"report_id": "…",
"collection_id": "…",
"collection_name": "…",
"resource": "zahlenwerk://report/…"
}
}data je Ereignis:
| Ereignis | Felder in data |
|---|---|
report.parsed | report_id, collection_id, collection_name, resource |
report.failed | report_id, collection_id, collection_name, error (lesbarer Grund, höchstens 500 Zeichen), resource |
document.extracted | document_id, document_type, position_id, position_ids (ein Auszug kann mehrere Positionen betreffen) |
position.created | position_id, instrument_type, name |
Signatur prüfen
Jede Anfrage trägt den Header:
Zahlenwerk-Signature: t=<Unix-Zeit>,v1=<Signatur>v1 ist ein HMAC-SHA256 über "<t>.<Body>" mit dem Geheimnis Ihres Webhooks. Prüfen Sie die Signatur und verwerfen Sie Anfragen, die älter als fünf Minuten sind.
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);
}Zustellung
- Jede Antwort außer 2xx gilt als Fehler, auch 4xx.
- Antwortet Ihr System nicht innerhalb von 10 Sekunden, gilt die Zustellung als fehlgeschlagen.
- Weiterleitungen (3xx) werden nicht verfolgt und gelten als Fehler.
- Fehlgeschlagene Zustellungen wiederholt Zahlenwerk bis zu viermal mit wachsendem Abstand. Ihr System sollte doppelte Anfragen vertragen.
Anforderungen
- Nur HTTPS-Endpunkte.
- Interne und private Adressen werden abgelehnt.
Eine allgemeine REST-API gibt es nicht. Für lesenden und schreibenden Zugriff nutzen Sie den MCP-Endpunkt.