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 エンドポイントが返す形式と同じです。 |
署名を検証する
エンドポイントごとに専用の署名シークレットがあり、追加時に一度だけ表示されます。処理する前に、すべてのリクエストを確認してください。
- 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 | 証明書の有効期限が切れました。 |