İçindekiler
Abonelik açmakOlaylarBildirimin içeriğiİmzayı doğrulamakTeslim, yeniden deneme ve ölü mektupTeslim günlüğü ve yeniden gönderSunucu şifreleme anahtarıOpenAPI uç özetiTelefondaWebhook ve OpenAPI: başka sistemlere olay bildirimi
Webhook, HNR'de bir olay olduğunda (fatura yazıldı, sipariş silindi, sevkiyat yola çıktı…) belirlediğiniz adrese imzalı bir HTTP bildirimi gönderir. Bildirim yalnız belgenin özetini ve API bağlantısını taşır; alıcı tam kaydı kendi oturumuyla API'den okur. Bu sayfa bir sözleşme açıklamasıdır, resmî bir şema değildir.
Abonelik açmak
Ayarlar › Entegrasyon ve webhook'lar bölümü yalnız sistem yöneticisine açıktır. Yeni abonelikte bir ad, hedef adres ve en az bir olay seçilir. Adres https ile başlamalıdır; yerel ağdaki ya da bu bilgisayardaki bir hedef (ör. 192.168.x.x, localhost) ancak yönetici onayı kutusu işaretlenirse kabul edilir. Aynı adres için ikinci abonelik açılamaz.
İsteğe bağlı süzgeçler: yalnız belirli cariler ya da depolar. Süzgeç tanımlıysa ve belgede o alan yoksa bildirim gönderilmez. Belge tutarı ve dövizi yalnız “Belge tutarını ve dövizini bildirime ekle” işaretliyse gönderilir.
Kaydedince gizli anahtar (whsec_ ile başlar) yalnız bir kez gösterilir; alıcı sisteme kaydedin. Sunucuda şifreli saklanır ve bir daha okunamaz. Kaybederseniz “Anahtarı yenile” ile yenisini üretin; eski anahtarla imza artık doğrulanmaz.
Olaylar
fatura, sipariş, teklif: yazildi, degisti, silindi · irsaliye: yazildi, silindi · makbuz: yazildi, degisti, silindi · stok.hareket (depolar arası transfer sevki, teslimi ya da firesi; sayım onayı) · sevkiyat.durum (yola çıkış, durak teslimi, POD düzeltmesi) · onay.karar · dof.acildi · servis.bilet (açıldı, durum) · uretim.teyit (teyit ya da iptal). Olay kodu X-HNR-Event başlığında ve gövdenin olay alanındadır; test düğmesi test.ping gönderir.
Bildirimin içeriği
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 kesin belge numarasıdır; baglanti ile tam kayıt API'den okunur. tutar ve doviz yalnız tutar dâhil aboneliklerde gelir; doviz yoksa tutar firmanın yerel parasıdır. Silme olayında özet, belge silinmeden önce okunur. surum yük biçiminin sürümüdür: yeni alan eklenebilir, var olan alan değişmez.
İmzayı doğrulamak
Her istekte X-HNR-Event, X-HNR-Delivery (teslim kimliği), X-HNR-Timestamp ve X-HNR-Signature: t=…,v1=… başlıkları gelir. v1, gizli anahtarla t + "." + ham gövde metninin HMAC-SHA256 özetidir (onaltılık). Alıcı imzayı sabit zamanlı karşılaştırmayla doğrulamalı, 5 dakikadan eski zamanı reddetmeli ve aynı X-HNR-Delivery değerini ikinci kez işlememeli; ama yine 2xx dönmelidir (tekrar koruması).
// 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', '')) Teslim, yeniden deneme ve ölü mektup
HNR adresinize POST eder ve 10 saniye bekler; yalnız 2xx yanıt teslim sayılır, yönlendirme izlenmez. Başarısız denemeden sonraki bekleme sırasıyla yaklaşık 1 dk, 3 dk, 11 dk, 38 dk, 2 sa, 7 sa ve 24 sa'tir. Sekiz deneme de başarısızsa teslim ölü mektuba düşer. Aynı abonelik ve aynı belge için bildirimler sırayla gider: önceki teslim bitmeden sonraki gönderilmez. Firma başına aynı anda en çok 4 gönderim yapılır.
Abonelik yoksa sunucu hiçbir şey göndermez. Gönderim sunucunun kendi firmasında dakikada bir; öteki firmalarda o firmada yeni bir işlem yapıldığında çalışır. Durdurulan abonelikte bekleyen bildirimler bekler, yeniden etkinleştirilince gider.
Teslim günlüğü ve yeniden gönder
Teslim günlüğü her bildirimin durumunu (bekliyor, teslim edildi, ölü mektup), deneme sayısını ve son HTTP kodunu gösterir; ayrıntıda gönderilen gövde, yanıtın ilk 1 KB'ı ve her deneme listelenir. “Yeniden gönder” bildirimi aynı teslim kimliğiyle hemen bir kez daha gönderir; başarısızsa yeniden deneme kuralı baştan işler. Kayıtlar silinmez. “Test gönder” abonelik adresine test.ping olayı yollar.
Sunucu şifreleme anahtarı
Gizli anahtarlar, canlı banka bağlantısıyla aynı sunucu şifreleme anahtarıyla (HNR_BANKA_KIMLIK_ANAHTARI) AES-256-GCM ile saklanır. Bu anahtar tanımlı değilse abonelik kaydedilemez. Anahtar değişirse kayıtlı gizli anahtarlar çözülemez; her abonelikte “Anahtarı yenile” gerekir.
OpenAPI uç özeti
GET /api/openapi.json (ya da Entegrasyon bölümündeki indirme düğmesi) sunucunun o anda açık bütün API uçlarını yol, yöntem ve modül etiketiyle listeler. İstek ve yanıt gövdeleri belgelenmez: bu bir uç özetidir, resmî şema değildir. Kimlik: Authorization: Bearer API anahtarı ve X-Oturum-Token.
Telefonda
Telefonda abonelikler kart olarak görünür; yeni abonelik üç adımda açılır (Adres, Olaylar, Süzgeç). Teslim günlüğü kart listesidir; her kartta Ayrıntı ve Yeniden gönder düğmeleri vardır.
İlgili rehberler
- Departmanlar — Arka Ofis İçin Sıfırdan RehberBu pencere tek bir iş yapmaz; on ayrı departmanın defterini bir arada tutar. Korkmayın: hiç kimse onunu birden kullanmaz.
- Entegrasyon kataloğu: HNR neye bağlanır?Bu sayfa HNR'nin bankaya, kargoya, pazaryerine, vergi idaresine, muhasebe dosyalarına ve başka programlara nasıl bağlandığını tek yerde toplar.
- Baskı Formları — kâğıda çıkanı siz tasarlarsınızEskiden teklif, fatura ve makbuz formları programın içine gömülüydü; değiştirmek için yazılımcı gerekiyordu. Artık formu siz kuruyorsunuz.
- Denetim İzi, Güvenlik Kapıları ve AnormalliklerBu rehber üç ayrı savunma katmanını anlatır. Kısaca: birincisi yazar, ikincisi durdurur, üçüncüsü gösterir. Üçü ayrı ayrı işe yarar ama asıl gücü birlikte.
- Belge Numarası Serileri — Sıfırdan RehberHer kesin belgenin — fatura, irsaliye, sipariş, teklif, makbuz, çek bordrosu — müşteriye, muhasebeciye ve vergi dairesine gösterilen bir numarası vardır.
- Bildirim ve Onay Merkezi — Sıfırdan RehberOnay bekleyen işler programın on ayrı köşesinde durur: kredi limiti bir yerde, fatura eşleşme farkı başka yerde, izin talebi İK'da.