Содержание
Создание подпискиСобытияСодержимое уведомленияПроверка подписиДоставка, повторы и недоставленныеЖурнал доставки и повторная отправкаКлюч шифрования сервераСводка конечных точек OpenAPIНа телефонеWebhook и OpenAPI: уведомления о событиях для других систем
Когда в HNR происходит событие (счёт проведён, заказ удалён, отгрузка в пути…), webhook отправляет подписанное HTTP-уведомление на заданный вами адрес. Оно содержит только сводку документа и ссылку API; получатель читает полную запись через API своей сессией. Эта страница описывает соглашение, а не официальную схему.
Создание подписки
Настройки › Интеграция и webhook доступны только системному администратору. Для новой подписки нужны название, целевой адрес и хотя бы одно событие. Адрес должен начинаться с https; цель в локальной сети или на этом компьютере (например 192.168.x.x, localhost) принимается только при отмеченном одобрении администратора. Вторую подписку на тот же адрес создать нельзя.
Необязательные фильтры: только определённые контрагенты или склады. Если фильтр задан, а в документе такого поля нет, уведомление не отправляется. Сумма и валюта документа отправляются, только если отмечено «Добавлять сумму и валюту документа в уведомление».
При сохранении секрет подписи (начинается с whsec_) показывается только один раз; сохраните его в принимающей системе. На сервере он хранится в зашифрованном виде и повторно не читается. Если потеряете, создайте новый кнопкой «Обновить секрет»; подписи старым секретом перестают проходить проверку.
События
счёт, заказ, предложение (fatura, siparis, teklif): yazildi, degisti, silindi · накладная (irsaliye): yazildi, silindi · квитанция (makbuz): yazildi, degisti, silindi · stok.hareket (перемещение между складами отправлено, получено или списано; утверждение инвентаризации) · sevkiyat.durum (выезд, доставка в точке, исправление POD) · onay.karar · dof.acildi · servis.bilet (открыта, статус) · uretim.teyit (подтверждение или отмена). Код события передаётся в заголовке X-HNR-Event и в поле olay тела; кнопка теста отправляет test.ping.
Содержимое уведомления
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 — окончательный номер документа; полную запись читают через API по baglanti. tutar и doviz приходят только в подписках с суммой; без doviz сумма в местной валюте фирмы. Для события удаления сводка читается до удаления документа. surum — версия формата: новые поля могут добавляться, существующие не меняются.
Проверка подписи
Каждый запрос содержит заголовки X-HNR-Event, X-HNR-Delivery (идентификатор доставки), X-HNR-Timestamp и X-HNR-Signature: t=…,v1=…. v1 — HMAC-SHA256 (hex) текста t + "." + исходное тело с секретом подписи. Получатель должен проверять подпись сравнением за постоянное время, отклонять метки старше 5 минут и не обрабатывать один и тот же X-HNR-Delivery дважды, но всё равно отвечать 2xx (защита от повтора).
// 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', '')) Доставка, повторы и недоставленные
HNR отправляет POST на ваш адрес и ждёт 10 секунд; доставкой считается только ответ 2xx, перенаправления не выполняются. После неудачи ожидание составляет примерно 1 мин, 3 мин, 11 мин, 38 мин, 2 ч, 7 ч и 24 ч. Если все восемь попыток неудачны, доставка становится недоставленной. Уведомления одной подписки по одному документу идут по порядку: следующее не отправляется, пока не завершена предыдущая доставка. Одновременно не более 4 доставок на фирму.
Без подписки сервер ничего не отправляет. Доставка выполняется каждую минуту в собственной фирме сервера; в других фирмах — при каждой новой операции в них. В остановленной подписке ожидающие уведомления ждут и уходят после повторного включения.
Журнал доставки и повторная отправка
Журнал доставки показывает статус каждого уведомления (ожидает, доставлено, недоставлено), число попыток и последний HTTP-код; в подробностях — отправленное тело, первый 1 КБ ответа и каждая попытка. «Отправить повторно» сразу отправляет уведомление ещё раз с тем же идентификатором доставки; при неудаче правило повторов начинается заново. Записи никогда не удаляются. «Отправить тест» шлёт событие test.ping на адрес подписки.
Ключ шифрования сервера
Секреты подписи хранятся с AES-256-GCM под тем же ключом шифрования сервера, что и прямое банковское подключение (HNR_BANKA_KIMLIK_ANAHTARI). Если ключ не задан, подписку сохранить нельзя. Если ключ изменится, сохранённые секреты не расшифровываются и для каждой подписки нужно «Обновить секрет».
Сводка конечных точек OpenAPI
GET /api/openapi.json (или кнопка скачивания в разделе Интеграция) перечисляет все открытые сейчас конечные точки API сервера с путём, методом и меткой модуля. Тела запросов и ответов не описываются: это сводка конечных точек, а не официальная схема. Аутентификация: API-ключ в Authorization: Bearer и X-Oturum-Token.
На телефоне
На телефоне подписки показываются карточками; новая подписка создаётся в три шага (Адрес, События, Фильтр). Журнал доставки — список карточек; на каждой есть кнопки «Подробнее» и «Отправить повторно».
Связанные руководства
- Отделы — Руководство от Scratch для задней офисаЭто окно не делает одну работу; оно держит Подразделения из различных отделений Не беспокойтесь: никто не использует все десять.
- Каталог интеграций: к чему подключается HNR?На этой странице собрано в одном месте, как HNR подключается к банкам, службам доставки, маркетплейсам, налоговой службе.
- Формы печати — вы проектируете то, что идет на бумагеЦитата, счета и распределения поступлений использовались для похоронения внутри программы; изменение одного требовало разработчика.
- Аудитный маршрут, ворота безопасности и аномалииЭтот водитель охватывает три отдельных слоя обороны. в кратком смысле: первый Рекорд, Второй СТАЙ, Третий показы. Каждый из них полезен сам по себе.
- Серия номерных документов — Руководство от ScratchКаждый конечный документ — счета, нота о доставке, заказа, цитата, получения, чека — имеет номер, который показан клиенту, бухгалтеру и налоговому бюро.
- Центр уведомления и утверждения — Руководство от ScratchРабота, ожидающая одобрения, находится в десять разных углах программы: кредитный лимит в одном месте, счета соответствует различию в другом.