Legitmark は 3 種類のイベントタイプを送信します。すべての Webhook 送信先は自動的にすべてのイベントを受信します。
state_change
サービスリクエストが新しいステータスに遷移したときに送信されます。鑑定の進捗と結果を追跡するための主要なイベントです。
Payload
{
"event_type": "state_change",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"state": {
"primary": "COMPLETE",
"supplement": "APPROVED"
},
"timestamp": "2026-02-10T12:00:00.000Z"
}
フィールド
貴社の内部商品 ID — サービスリクエスト作成時に設定した external_id。
ステータス変更が発生した時点の ISO 8601 タイムスタンプ。
ステータス遷移
以下の表は、処理すべき最も一般的なステータス遷移を示しています：
state.primary | state.supplement | 意味 |
|---|
QC | PENDING | 写真が送信され、品質審査中 |
QC | REJECTED | 写真が品質審査に不合格 — 詳細を含む media_rejected イベントが続きます |
QC | APPROVED | 写真が品質審査を通過、鑑定開始 |
UNDERWAY | ASSIGNED | 鑑定士が割り当てられた |
COMPLETE | APPROVED | 商品は本物 |
COMPLETE | REJECTED | 商品は本物ではない |
最も重要なステータス遷移は COMPLETE + APPROVED または COMPLETE + REJECTED です — これが最終鑑定結果です。完全なステートマシンについてはサービスリクエストのステータスをご覧ください。TypeScript SDK（v0.2.0+）を使用すると、文字列を手動で比較する代わりに isAuthentic(event) と isCounterfeit(event) でチェックできます。Webhook 処理ガイドを参照してください。
アップロードされた画像が品質管理に通らなかった場合に送信されます。拒否された各画像には面の名前と拒否理由が含まれており、ユーザーに特定の写真の再アップロードを促すことができます。
Payload
{
"event_type": "media_rejected",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"sides": [
{
"side": "Front",
"reason": "画像がぼやけている",
"message": "提出された画像がぼやけすぎています。より鮮明な写真を撮影し、動きを最小限に抑えて精度を高めてください。"
},
{
"side": "Interior",
"reason": "照明不足",
"message": "提出された画像の照明が不十分です。視認性を向上させるために、より良い照明で新しい写真を撮影してください。"
}
],
"timestamp": "2026-02-10T12:15:00.000Z"
}
フィールド
拒否された画像と理由の配列。
拒否された面の名前（例："Front"、"Label"、"Back"）。
拒否理由。Legitmark の理由データベースからの人間が読める文字列です（例："画像がぼやけている"、"照明不足"）。新しい理由が追加されると値が変わる可能性があります。
ユーザーが問題を修正するためのガイダンスを含む詳細な説明。
media_rejected イベントを受信した場合、サービスリクエストを続行するには、ユーザーが拒否された特定の面の画像を再アップロードする必要があります。最適なユーザー体験のために、side の名前と message を使ってユーザーに通知してください。
TypeScript SDK を使用すると、needsResubmission(event) がこのイベントタイプに対して true を返します。Webhook 処理ガイドを参照してください。
invalidate_sr
サービスリクエストがキャンセルされた場合に送信されます。
Payload
{
"event_type": "invalidate_sr",
"sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
"reference_id": "YOUR-INTERNAL-ITEM-ID",
"invalidation_reason": {
"code": "CANCELLED",
"message": "Service request cancelled"
},
"timestamp": "2026-02-10T14:30:00.000Z"
}
フィールド
表示 invalidation_reason プロパティ
理由コード。現在は常に "CANCELLED" です。将来、追加のコードが導入される可能性があります。
現在は "Service request cancelled" です。具体的なキャンセル理由はメールで別途エンドユーザーに通知されます。
