Everdeen Passport
한국어
무료로 시작

웹훅

회사 데이터에 변경이 생기면 해당 이벤트를 구독한 모든 엔드포인트로 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 엔드포인트가 반환하는 형식과 같습니다.

서명 확인

엔드포인트마다 고유한 서명 시크릿이 있으며, 엔드포인트를 추가할 때 한 번만 표시됩니다. 요청을 처리하기 전에 매번 확인하세요.

  1. Evd-Signature 헤더에서 t(초 단위 Unix 시간)와 v1을 읽습니다.
  2. 시크릿으로 t, 마침표, 그리고 받은 그대로의 원본 요청 본문에 대해 HMAC-SHA256을 계산합니다.
  3. 상수 시간 비교로 결과를 v1과 대조합니다.
  4. t가 자체 시스템 시계와 5분 넘게 차이 나면 요청을 거부합니다.
  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 값이 나와야 합니다.

secretexample-secret
t1767225600
body{"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"}
v121cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40

재시도와 재전송

빠르게 응답하고 오래 걸리는 작업은 응답 후에 처리하세요. 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인증서가 만료되었습니다.