Skip to content
HNROS Help Center
English
Start free
ContentsCreating a subscriptionEventsWhat the notification containsVerifying the signatureDelivery, retries and dead letterDelivery log and resendServer encryption keyOpenAPI endpoint summaryOn the phone

Webhooks 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