Contents
Creating a subscriptionEventsWhat the notification containsVerifying the signatureDelivery, retries and dead letterDelivery log and resendServer encryption keyOpenAPI endpoint summaryOn the phoneWebhooks and OpenAPI: event notifications to other systems
When an event happens in HNR (invoice posted, order deleted, shipment left…), a webhook sends a signed HTTP notification to the address you set. The notification carries only a summary of the document and its API link; the receiver reads the full record from the API with its own session. This page describes a contract; it is not an official schema.
Creating a subscription
Settings › Integration and webhooks is open only to the system administrator. A new subscription needs a name, a target address and at least one event. The address must start with https; a target on the local network or on this computer (e.g. 192.168.x.x, localhost) is accepted only if the administrator approval box is ticked. A second subscription for the same address cannot be created.
Optional filters: only certain accounts or warehouses. If a filter is set and the document has no such field, no notification is sent. The document amount and currency are sent only if “Add the document amount and currency to the notification” is ticked.
On saving, the signing secret (starting with whsec_) is shown only once; store it in the receiving system. It is kept encrypted on the server and cannot be read again. If you lose it, generate a new one with “Renew secret”; signatures made with the old secret no longer verify.
Events
invoice, order, quotation (fatura, siparis, teklif): yazildi, degisti, silindi · delivery note (irsaliye): yazildi, silindi · receipt (makbuz): yazildi, degisti, silindi · stok.hareket (inter-warehouse transfer shipped, received or lost; count approval) · sevkiyat.durum (departure, stop delivered, POD correction) · onay.karar · dof.acildi · servis.bilet (opened, status) · uretim.teyit (confirmation or cancellation). The event code is in the X-HNR-Event header and in the olay field of the body; the test button sends test.ping.
What the notification contains
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 is the final document number; the full record is read from the API through baglanti. tutar and doviz come only with subscriptions that include amounts; without doviz the amount is in the company's local currency. For a delete event the summary is read before the document is deleted. surum is the payload format version: new fields may be added, existing fields do not change.
Verifying the signature
Each request carries the headers X-HNR-Event, X-HNR-Delivery (delivery ID), X-HNR-Timestamp and X-HNR-Signature: t=…,v1=…. v1 is the HMAC-SHA256 (hex) of the text t + "." + raw body with the signing secret. The receiver should verify the signature with a constant-time comparison, reject timestamps older than 5 minutes, and not process the same X-HNR-Delivery twice while still answering 2xx (replay protection).
// 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', '')) Delivery, retries and dead letter
HNR POSTs to your address and waits 10 seconds; only a 2xx answer counts as delivered and redirects are not followed. After a failed attempt the waits are about 1 min, 3 min, 11 min, 38 min, 2 h, 7 h and 24 h. If all eight attempts fail, the delivery becomes a dead letter. Notifications for the same subscription and the same document go in order: the next is not sent before the previous delivery finishes. At most 4 deliveries run at once per company.
Without a subscription the server sends nothing. Delivery runs every minute in the server's own company; in other companies it runs whenever a new operation is made in that company. For a stopped subscription pending notifications wait and go out once it is enabled again.
Delivery log and resend
The delivery log shows each notification's status (pending, delivered, dead letter), attempt count and last HTTP code; the details list the body sent, the first 1 KB of the response and every attempt. “Resend” sends the notification once more right away with the same delivery ID; if it fails, the retry rule starts over. Records are never deleted. “Send test” sends a test.ping event to the subscription address.
Server encryption key
Signing secrets are stored with AES-256-GCM under the same server encryption key as the live bank connection (HNR_BANKA_KIMLIK_ANAHTARI). If this key is not defined, a subscription cannot be saved. If the key changes, stored secrets cannot be decrypted and each subscription needs “Renew secret”.
OpenAPI endpoint summary
GET /api/openapi.json (or the download button in the Integration section) lists every API endpoint the server currently exposes, with path, method and module tag. Request and response bodies are not documented: this is an endpoint summary, not an official schema. Authentication: the Authorization: Bearer API key and X-Oturum-Token.
On the phone
On a phone, subscriptions appear as cards; a new subscription is created in three steps (Address, Events, Filter). The delivery log is a card list; each card has Details and Resend buttons.
Related guides
- Departments — A Guide from Scratch for the Back OfficeThis window does not do one job; it holds the ledgers of ten different departments side by side. Do not be alarmed: nobody uses all ten.
- Integration catalogue: what does HNR connect to?This page gathers in one place how HNR connects to banks, carriers, marketplaces, the tax office, accounting files and other programs.
- Print Forms — you design what goes on paperQuote, invoice and receipt layouts used to be buried inside the program; changing one required a developer. Now you build the form.
- Audit Trail, Security Gates and AnomaliesThis guide covers three separate layers of defence. In short: the first one records, the second stops, the third shows. Each is useful on its own.
- Document Number Series — A Guide from ScratchEvery final document — invoice, delivery note, order, quotation, receipt, cheque batch — has a number that is shown to the customer.
- Notification and Approval Center — A Guide from ScratchWork waiting for approval sits in ten different corners of the program: the credit limit in one place, the invoice matching difference in another.