Inhalt
Abonnement anlegenEreignisseInhalt der BenachrichtigungSignatur prüfenZustellung, Wiederholungen und UnzustellbaresZustellprotokoll und erneutes SendenVerschlüsselungsschlüssel des ServersOpenAPI-EndpunktübersichtAuf dem TelefonWebhooks und OpenAPI: Ereignisbenachrichtigung an andere Systeme
Tritt in HNR ein Ereignis ein (Rechnung gebucht, Auftrag gelöscht, Sendung unterwegs…), sendet der Webhook eine signierte HTTP-Benachrichtigung an die von Ihnen festgelegte Adresse. Sie enthält nur eine Zusammenfassung des Belegs und seinen API-Link; der Empfänger liest den vollständigen Datensatz mit seiner eigenen Sitzung über die API. Diese Seite beschreibt eine Vereinbarung, kein offizielles Schema.
Abonnement anlegen
Einstellungen › Integration und Webhooks steht nur dem Systemadministrator offen. Ein neues Abonnement braucht einen Namen, eine Zieladresse und mindestens ein Ereignis. Die Adresse muss mit https beginnen; ein Ziel im lokalen Netz oder auf diesem Computer (z. B. 192.168.x.x, localhost) wird nur akzeptiert, wenn das Feld für die Administratorfreigabe angekreuzt ist. Für dieselbe Adresse ist kein zweites Abonnement möglich.
Optionale Filter: nur bestimmte Konten oder Lager. Ist ein Filter gesetzt und fehlt dem Beleg dieses Feld, wird keine Benachrichtigung gesendet. Betrag und Währung werden nur gesendet, wenn „Betrag und Währung des Belegs in die Benachrichtigung aufnehmen“ angekreuzt ist.
Beim Speichern wird das Signaturgeheimnis (beginnt mit whsec_) nur einmal angezeigt; speichern Sie es im Empfängersystem. Es wird verschlüsselt auf dem Server abgelegt und kann nicht erneut gelesen werden. Bei Verlust erzeugen Sie mit „Geheimnis erneuern“ ein neues; Signaturen mit dem alten Geheimnis sind dann ungültig.
Ereignisse
Rechnung, Auftrag, Angebot (fatura, siparis, teklif): yazildi, degisti, silindi · Lieferschein (irsaliye): yazildi, silindi · Beleg (makbuz): yazildi, degisti, silindi · stok.hareket (Umlagerung zwischen Lagern versandt, empfangen oder Schwund; Inventurfreigabe) · sevkiyat.durum (Abfahrt, Stopp zugestellt, POD-Korrektur) · onay.karar · dof.acildi · servis.bilet (eröffnet, Status) · uretim.teyit (Rückmeldung oder Storno). Der Ereigniscode steht im Header X-HNR-Event und im Feld olay des Inhalts; die Testschaltfläche sendet test.ping.
Inhalt der Benachrichtigung
POST https://alici.ornek.com/hnr
Content-Type: application/json; charset=utf-8
User-Agent: HNR-Webhook/1
X-HNR-Event: fatura.yazildi
X-HNR-Delivery: wh_2
X-HNR-Timestamp: 1791559000
X-HNR-Signature: t=1791559000,v1=5f1c…(64 hex)
{"surum":1,"id":"ev_3fa1…","olay":"fatura.yazildi","firma":"ornek","zaman":"2026-10-09T15:15:00.000Z",
"belge":{"tur":"fatura","sira":9107041,"no":"SF2026000126","cari":"C001","depo":"MERKEZ","tarih":"2026-10-09","tutar":360},
"baglanti":"/api/fatura/9107041"} belge.no ist die endgültige Belegnummer; den vollständigen Datensatz liest man über baglanti aus der API. tutar und doviz kommen nur bei Abonnements mit Betrag; ohne doviz ist der Betrag in der Landeswährung der Firma. Bei einem Löschereignis wird die Zusammenfassung vor dem Löschen gelesen. surum ist die Formatversion: Neue Felder können hinzukommen, bestehende ändern sich nicht.
Signatur prüfen
Jede Anfrage enthält die Header X-HNR-Event, X-HNR-Delivery (Zustell-ID), X-HNR-Timestamp und X-HNR-Signature: t=…,v1=…. v1 ist der HMAC-SHA256 (hex) des Textes t + "." + Rohinhalt mit dem Signaturgeheimnis. Der Empfänger sollte die Signatur zeitkonstant vergleichen, Zeitstempel älter als 5 Minuten ablehnen und dieselbe X-HNR-Delivery nicht zweimal verarbeiten, aber trotzdem 2xx antworten (Schutz vor Wiederholung).
// Node.js (express.raw ile ham gövde / raw body)
import { createHmac, timingSafeEqual } from 'node:crypto';
const seen = new Set();
export function verify(secret, headers, rawBody) {
const p = Object.fromEntries(String(headers['x-hnr-signature']).split(',').map((x) => x.split('=')));
if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return 'old';
const expected = createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest();
const got = Buffer.from(p.v1 || '', 'hex');
if (got.length !== expected.length || !timingSafeEqual(got, expected)) return 'bad';
const id = headers['x-hnr-delivery'];
if (seen.has(id)) return 'duplicate'; // answer 2xx, do not process again
seen.add(id); return 'ok';
} # Python 3
import hmac, hashlib, time
def verify(secret: str, signature: str, raw_body: bytes) -> bool:
p = dict(x.split('=', 1) for x in signature.split(','))
if abs(time.time() - int(p['t'])) > 300:
return False
expected = hmac.new(secret.encode(), p['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, p.get('v1', '')) Zustellung, Wiederholungen und Unzustellbares
HNR sendet einen POST an Ihre Adresse und wartet 10 Sekunden; nur eine 2xx-Antwort gilt als zugestellt, Weiterleitungen werden nicht verfolgt. Nach einem Fehlversuch wird etwa 1 Min., 3 Min., 11 Min., 38 Min., 2 Std., 7 Std. und 24 Std. gewartet. Scheitern alle acht Versuche, wird die Zustellung unzustellbar. Benachrichtigungen desselben Abonnements zum selben Beleg gehen der Reihe nach: Die nächste wird erst nach Abschluss der vorherigen gesendet. Pro Firma laufen höchstens 4 Zustellungen gleichzeitig.
Ohne Abonnement sendet der Server nichts. Die Zustellung läuft in der eigenen Firma des Servers jede Minute; in anderen Firmen jedes Mal, wenn dort ein neuer Vorgang erfolgt. Bei einem gestoppten Abonnement warten offene Benachrichtigungen und gehen nach erneuter Aktivierung hinaus.
Zustellprotokoll und erneutes Senden
Das Zustellprotokoll zeigt für jede Benachrichtigung den Status (ausstehend, zugestellt, unzustellbar), die Zahl der Versuche und den letzten HTTP-Code; die Details enthalten den gesendeten Inhalt, die ersten 1 KB der Antwort und jeden Versuch. „Erneut senden“ schickt die Benachrichtigung sofort noch einmal mit derselben Zustell-ID; schlägt das fehl, beginnt die Wiederholungsregel von vorn. Einträge werden nie gelöscht. „Test senden“ schickt ein test.ping-Ereignis an die Abonnementadresse.
Verschlüsselungsschlüssel des Servers
Signaturgeheimnisse werden mit AES-256-GCM unter demselben Server-Verschlüsselungsschlüssel wie die Live-Bankverbindung gespeichert (HNR_BANKA_KIMLIK_ANAHTARI). Ist dieser Schlüssel nicht definiert, kann kein Abonnement gespeichert werden. Ändert sich der Schlüssel, lassen sich gespeicherte Geheimnisse nicht entschlüsseln und jedes Abonnement braucht „Geheimnis erneuern“.
OpenAPI-Endpunktübersicht
GET /api/openapi.json (oder die Download-Schaltfläche im Bereich Integration) listet alle derzeit offenen API-Endpunkte des Servers mit Pfad, Methode und Modul-Tag. Anfrage- und Antworttexte werden nicht dokumentiert: Dies ist eine Endpunktübersicht, kein offizielles Schema. Authentifizierung: API-Schlüssel per Authorization: Bearer und X-Oturum-Token.
Auf dem Telefon
Auf dem Telefon erscheinen Abonnements als Karten; ein neues Abonnement wird in drei Schritten angelegt (Adresse, Ereignisse, Filter). Das Zustellprotokoll ist eine Kartenliste; jede Karte hat die Schaltflächen Details und Erneut senden.
Verwandte Anleitungen
- Abteilungen — Ein Guide von Scratch für das Back OfficeDieses Fenster erledigt nicht nur eine Aufgabe, sondern zeigt die Aufzeichnungen von zehn verschiedenen Abteilungen nebeneinander.
- Integrationskatalog: Womit verbindet sich HNR?Diese Seite fasst an einem Ort zusammen, wie HNR sich mit Banken, Versanddienstleistern, Marktplätzen, dem Finanzamt, Buchhaltungsdateien und anderen.
- Druckformular – Sie entwerfen, was auf Papier gehtZitate, Rechnungen und Empfangsplätze werden verwendet, um innerhalb des Programms begraben zu werden; Veränderung eines erfordert einen Entwickler.
- Audit Trail, Sicherheitsschlüssel und AnomalienDieser Leitfaden umfasst drei separate Schichten der Verteidigung. kurz: die erste Rekord, Die zweite Stopp, Der dritte Show zeigt.
- Dokumentnummer Serie — Ein Guide von ScratchJedes letzte Dokument – Rechnung, Lieferbericht, Bestellung, Zitat, Empfang, Cheque-Buch – hat eine Nummer, die dem Kunden.
- Notifizierungs- und Genehmigungscenter – Ein Guide von ScratchArbeit wartet auf die Genehmigung sitzen in zehn verschiedenen Ecken des Programms: der Kreditgrenze an einem Ort, die Rechnung entspricht den Unterschied in.