웹훅
회사 데이터에 변경이 생기면 해당 이벤트를 구독한 모든 엔드포인트로 HTTPS 요청을 보냅니다. 엔드포인트는 대시보드의 연동 메뉴에서 추가하세요.
요청
POST | 저장한 엔드포인트 URL로 HTTPS를 통해 전송됩니다. 리디렉션은 따르지 않습니다. |
|---|---|
Content-Type | 본문은 JSON 형식의 이벤트이며, 아래에서 설명합니다. |
Evd-Signature | 요청에 서명한 시각과 HMAC-SHA256 서명입니다. |
페이로드
모든 이벤트는 같은 구조를 사용합니다. data 필드에 영향을 받은 레코드가 들어 있습니다.
{
"event_id": "evt_8KQ2M4ZP7T",
"type": "passport.published",
"created_at": "2026-10-31T02:15:00Z",
"test": false,
"data": {
"product_id": "prd_5F3K9W",
"version": 3,
"state": "PUBLISHED",
"signature_id": "sig_2RT8LQ",
"resolver_url": "https://pass.everdeenone.com/01/09506000134352",
"published_at": "2026-10-31T02:15:00Z",
"withdrawn_at": null
}
}
| 필드 | 설명 |
|---|---|
event_id | 이벤트마다 고유합니다. 이미 처리한 ID는 건너뛰세요. |
type | 이 페이지 끝의 목록에 있는 이벤트 이름입니다. |
created_at | 이벤트가 발생한 시각(UTC)입니다. |
test | 테스트 키로 발생한 이벤트이면 true입니다. |
data | 영향을 받은 레코드로, 해당 GET 엔드포인트가 반환하는 형식과 같습니다. |
서명 확인
엔드포인트마다 고유한 서명 시크릿이 있으며, 엔드포인트를 추가할 때 한 번만 표시됩니다. 요청을 처리하기 전에 매번 확인하세요.
- Evd-Signature 헤더에서 t(초 단위 Unix 시간)와 v1을 읽습니다.
- 시크릿으로 t, 마침표, 그리고 받은 그대로의 원본 요청 본문에 대해 HMAC-SHA256을 계산합니다.
- 상수 시간 비교로 결과를 v1과 대조합니다.
- t가 자체 시스템 시계와 5분 넘게 차이 나면 요청을 거부합니다.
- 이미 처리한 이벤트 ID는 건너뛰고 2xx 상태로 응답합니다.
import crypto from "node:crypto";
// rawBody: the request body as received (a Buffer), before JSON parsing.
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}import hashlib, hmac, time
# raw_body: the request body as received (bytes), before JSON parsing.
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t = parts.get("t", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(
secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))// rawBody: the request body as received, before JSON decoding.
func Verify(rawBody []byte, header, secret string) bool {
var t, v1 string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(p, "=")
switch k {
case "t":
t = v
case "v1":
v1 = v
}
}
ts, err := strconv.ParseInt(t, 10, 64)
if age := time.Now().Unix() - ts; err != nil || age > 300 || age < -300 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(rawBody)
given, err := hex.DecodeString(v1)
return err == nil && hmac.Equal(given, mac.Sum(nil))
}import 'dart:convert';
import 'package:crypto/crypto.dart';
// rawBody: the request body as received, before JSON decoding.
bool verify(List<int> rawBody, String header, String secret) {
final parts = <String, String>{};
for (final p in header.split(',')) {
final i = p.indexOf('=');
if (i > 0) parts[p.substring(0, i)] = p.substring(i + 1);
}
final t = int.tryParse(parts['t'] ?? '');
final now = DateTime.now().millisecondsSinceEpoch ~/ 1000;
if (t == null || (now - t).abs() > 300) return false;
final mac = Hmac(sha256, utf8.encode(secret))
.convert([...utf8.encode('${parts['t']}.'), ...rawBody]);
final expected = mac.toString();
final given = parts['v1'] ?? '';
if (given.length != expected.length) return false;
var diff = 0;
for (var i = 0; i < given.length; i++) {
diff |= given.codeUnitAt(i) ^ expected.codeUnitAt(i);
}
return diff == 0;
}코드 확인
이 시크릿, 타임스탬프, 본문으로 코드를 실행하면 이 v1 값이 나와야 합니다.
secret | example-secret |
|---|---|
t | 1767225600 |
body | {"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"} |
v1 | 21cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40 |
재시도와 재전송
빠르게 응답하고 오래 걸리는 작업은 응답 후에 처리하세요. 2xx가 아닌 응답, 리디렉션, 시간 초과는 실패한 시도로 간주됩니다. 약 24시간 동안 최대 8번 재시도한 뒤 해당 전송을 실패로 표시합니다. 대시보드나 API에서 어떤 전송이든 다시 보낼 수 있습니다.
이벤트
엔드포인트마다 받을 이벤트를 선택하세요.
| 이벤트 | 설명 |
|---|---|
product.created | 제품이 추가되었습니다. |
product.updated | 제품 정보가 변경되었습니다. |
item.created | 제품에 일련번호나 로트가 추가되었습니다. |
item.updated | 일련번호나 로트가 변경되었습니다. |
item.published | 일련번호나 로트의 여권이 게시되었습니다. |
item.withdrawn | 일련번호나 로트가 철회되었습니다. |
compliance.created | 인증서나 규정 준수 기록이 추가되었습니다. |
compliance.updated | 규정 준수 기록이 변경되었습니다. |
document.uploaded | 문서가 업로드되었습니다. |
extraction.completed | 문서의 데이터 추출이 완료되었습니다. |
review.required | 변경 사항이 검토를 기다리고 있습니다. |
review.approved | 검토자가 변경 사항을 승인했습니다. |
review.rejected | 검토자가 변경 사항을 반려했습니다. |
passport.published | 제품 여권이 게시되었습니다. |
passport.withdrawn | 제품 여권이 철회되었습니다. |
certificate.expiring | 인증서가 30일 이내에 만료됩니다. |
certificate.expired | 인증서가 만료되었습니다. |