Zum Inhalt springen
HNROS Hilfecenter
Deutsch
Kostenlos starten
InhaltAbonnement anlegenEreignisseInhalt der BenachrichtigungSignatur prüfenZustellung, Wiederholungen und UnzustellbaresZustellprotokoll und erneutes SendenVerschlüsselungsschlüssel des ServersOpenAPI-EndpunktübersichtAuf dem Telefon

Webhooks 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