Everdeen Passport
日本語
無料で始める

Webhook

御社のデータに変更があると、そのイベントを購読しているすべてのエンドポイントに 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証明書の有効期限が切れました。