웹훅과 OpenAPI: 다른 시스템으로 이벤트 알림
HNR에서 이벤트(송장 전기, 주문 삭제, 출하 출발…)가 발생하면 웹훅이 지정한 주소로 서명된 HTTP 알림을 보냅니다. 알림에는 문서 요약과 API 링크만 담기며, 수신 측은 자체 세션으로 API에서 전체 레코드를 읽습니다. 이 페이지는 계약 설명이며 공식 스키마가 아닙니다.
구독 만들기
설정 › 통합 및 웹훅은 시스템 관리자만 사용할 수 있습니다. 새 구독에는 이름, 대상 주소, 하나 이상의 이벤트가 필요합니다. 주소는 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는 확정 문서 번호이며, 전체 레코드는 baglanti로 API에서 읽습니다. tutar와 doviz는 금액 포함 구독에서만 오며, doviz가 없으면 금액은 회사 현지 통화입니다. 삭제 이벤트의 요약은 문서가 삭제되기 전에 읽습니다. surum은 페이로드 형식 버전으로, 새 필드는 추가될 수 있지만 기존 필드는 바뀌지 않습니다.
서명 검증
모든 요청에는 X-HNR-Event, X-HNR-Delivery(전송 ID), X-HNR-Timestamp, X-HNR-Signature: t=…,v1=… 헤더가 있습니다. v1은 서명 비밀키로 t + "." + 원본 본문을 계산한 HMAC-SHA256(16진수)입니다. 수신 측은 상수 시간 비교로 서명을 검증하고, 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시간입니다. 8회 모두 실패하면 배달 불가가 됩니다. 같은 구독·같은 문서의 알림은 순서대로 보내며, 이전 전송이 끝나기 전에는 다음을 보내지 않습니다. 회사당 동시 전송은 최대 4개입니다.
구독이 없으면 서버는 아무것도 보내지 않습니다. 전송은 서버 자체 회사에서는 1분마다, 다른 회사에서는 해당 회사에서 새 작업이 있을 때마다 실행됩니다. 중지된 구독의 대기 알림은 기다렸다가 다시 활성화되면 전송됩니다.
전송 로그와 다시 보내기
전송 로그는 각 알림의 상태(대기, 전달, 배달 불가), 시도 횟수, 마지막 HTTP 코드를 보여 주며, 세부 정보에는 보낸 본문, 응답의 처음 1KB, 각 시도가 나옵니다. “다시 보내기”는 같은 전송 ID로 즉시 한 번 더 보내고, 실패하면 재시도 규칙이 처음부터 적용됩니다. 기록은 삭제되지 않습니다. “테스트 보내기”는 구독 주소로 test.ping 이벤트를 보냅니다.
서버 암호화 키
서명 비밀키는 실시간 은행 연결과 같은 서버 암호화 키(HNR_BANKA_KIMLIK_ANAHTARI)로 AES-256-GCM 암호화되어 저장됩니다. 이 키가 정의되지 않으면 구독을 저장할 수 없습니다. 키가 바뀌면 저장된 비밀키를 복호화할 수 없으므로 각 구독에서 “비밀키 갱신”이 필요합니다.
OpenAPI 엔드포인트 요약
GET /api/openapi.json(또는 통합 섹션의 다운로드 버튼)는 서버가 현재 노출하는 모든 API 엔드포인트를 경로, 메서드, 모듈 태그와 함께 나열합니다. 요청·응답 본문은 문서화하지 않으므로 엔드포인트 요약이며 공식 스키마가 아닙니다. 인증: Authorization: Bearer API 키와 X-Oturum-Token.
휴대폰에서
휴대폰에서는 구독이 카드로 표시되며, 새 구독은 세 단계(주소, 이벤트, 필터)로 만듭니다. 전송 로그는 카드 목록이며 각 카드에 상세 보기와 다시 보내기 버튼이 있습니다.
관련 가이드
- 부서 - 뒷 사무실에 대한 Scratch의 가이드이 창은 하나의 작업을하지 않습니다; 그것은 개의 다른 부서의 좌석 옆에 앉아있다.
- 연동 카탈로그: HNR은 무엇과 연결되나요?이 페이지는 HNR이 은행, 택배사, 오픈마켓, 세무 당국, 회계 파일 및 다른 프로그램과 어떻게 연결되는지 한곳에 모았습니다.
- 인쇄 양식 - 당신은 종이에 무엇을 디자인인용, 청구 및 수신 배열은 프로그램 내부에 묻히기 위해 사용되었습니다; 하나를 변경하는 것은 개발자가 필요합니다.
- 검사 트랙, 보안 문 및 변형이 가이드는 개의 별도의 방어 층을 다루고 있습니다. 기록, 두 번째는 멈추기, 세 번째 쇼.
- 문서 번호 시리즈 - Scratch의 가이드모든 최종 문서 - 청구서, 배달 메모, 주문, 인용문, 수신, 체크 패치 - 고객, 회계사 및 세금 사무실에 표시되는 번호가 있습니다.
- Notification and Approval Center - Scratch의 가이드프로그램의 개 다른 각도에서 승인을 기다리는 작업 : 한 곳에 신용 제한, 다른 곳에 계좌 차이를 일치하는, 휴가 요청 HR.