Events
Webhooks
Listen for real-time events on the blockchain and inside the V-Ledger ecosystem to keep your ERP, CRM, and actor networks perfectly in sync.
How Webhooks Work
When an event occurs (e.g., a product is minted, ownership changes, or a deposit is released), V-Ledger sends an HTTP POST request to your configured endpoint. You can configure webhook URLs directly in the Brand Dashboard under Settings > Webhooks.
Supported Event Types
asset.initialized
Triggered when a hardware chip is successfully enrolled and registered (Workflow 1). Indicates raw inventory is available for binding.
Payload Example▼
{
"eventId": "evt_4B712A93DC",
"eventType": "asset.initialized",
"timestamp": "2026-05-03T16:40:00.000Z",
"data": {
"chipUid": "041C4D42152390",
"status": "INACTIVE",
"enrolledAt": "2026-05-03T16:40:00.000Z"
}
}asset.minted
Triggered when the L2 blockchain transaction completes and the digital twin is officially minted.
Payload Example▼
{
"eventId": "evt_9F821A723C",
"eventType": "asset.minted",
"timestamp": "2026-05-03T16:44:12.182Z",
"data": {
"tokenId": "1157018053583760",
"chipUid": "041C4D42152390",
"gtin": "04200000000001",
"brand": "0xab0f91D9F52c461F8a3B6208969fD663cB61f420",
"deposit": "1.62",
"transactionHash": "0x8fae83...a21"
}
}asset.customs_cleared
Triggered on cross-border transition when a customs authority updates the token status (e.g., cleared for European market entry).
Payload Example▼
{
"eventId": "evt_4C82A1389D",
"eventType": "asset.customs_cleared",
"timestamp": "2026-05-03T16:51:10.000Z",
"data": {
"tokenId": "1157018053583760",
"action": "CUSTOMS_CLEARED",
"actor": "[email protected]",
"locationName": "Port of Hamburg Customs Hub",
"latitude": 53546000,
"longitude": 9961000,
"transactionHash": "0x78af32...10a"
}
}asset.shipped / asset.delivered
Emitted when a logistics provider logs shipping manifest transitions, ensuring real-time track and trace.
Payload Example▼
{
"eventId": "evt_3A18B928C1",
"eventType": "asset.shipped",
"timestamp": "2026-05-03T16:52:12.410Z",
"data": {
"tokenId": "1157018053583760",
"action": "SHIPPED",
"actor": "[email protected]",
"locationName": "Central Distribution Hub",
"latitude": 51456000,
"longitude": 7012000,
"transactionHash": "0x12bc81...9c2"
}
}asset.sold
Dispatched upon physical purchase at the point-of-sale, triggering the start of the warranty period and CRM workflows.
Payload Example▼
{
"eventId": "evt_1F42B9302E",
"eventType": "asset.sold",
"timestamp": "2026-05-03T16:53:01.000Z",
"data": {
"tokenId": "1157018053583760",
"action": "SOLD",
"actor": "[email protected]",
"locationName": "Berlin Flagship Store",
"latitude": 52520000,
"longitude": 13405000,
"transactionHash": "0xef3201...ab1"
}
}payment_intent.succeeded (Stripe Checkout)
Received on POST /v1/public/webhook/checkout. Automatically triggers on-chain authorization (via the platform admin key) of the buyer's smart account upon successful payment.
Payload Example▼
{
"id": "evt_1OpR9LDBa8oM1U1X2345678",
"type": "payment_intent.succeeded",
"data": {
"object": {
"id": "pi_1OpR9LDBa8oM1U1X",
"amount": 50000,
"currency": "eur",
"metadata": {
"tokenId": "1",
"buyerWallet": "0x93FA56...77D"
}
}
}
}asset.transferred / asset.resold
Triggered when the physical item changes ownership via the secondary/resale market, updating global warranty status.
Payload Example▼
{
"eventId": "evt_2D813F421B",
"eventType": "asset.transferred",
"timestamp": "2026-05-03T16:45:30.000Z",
"data": {
"tokenId": "1157018053583760",
"from": "0xab0f91D9F52c461F8a3B6208969fD663cB61f420",
"to": "0x56aD9183E20B8C...32c",
"salePrice": "45.00",
"transactionHash": "0x2db428...12b"
}
}asset.recycled
Triggered when a certified facility marks the item as recycled. The circular deposit is released at this moment.
Payload Example▼
{
"eventId": "evt_8E129A88F1",
"eventType": "asset.recycled",
"timestamp": "2026-05-03T16:47:01.442Z",
"data": {
"tokenId": "1157018053583760",
"recycler": "0xRecyclerHubAddress...",
"rewardReceiver": "0xRewardPayoutAddress...",
"depositReleased": "1.62",
"transactionHash": "0xac63b...1e1"
}
}Verifying Webhook Signatures
To ensure the webhook actually came from V-Ledger, we include a cryptographic signature in the vledger-signature header. You should compute the HMAC SHA-256 of the payload using your Webhook Secret and compare it to the header.
const crypto = require('crypto');
function verifyWebhook(payload, signatureHeader, secret) {
const hmac = crypto.createHmac('sha256', secret);
const digest = hmac.update(payload).digest('hex');
return signatureHeader === digest;
}Retry Policy
If your server does not respond with a 2xx status code, V-Ledger queues the event for retry with exponential backoff over a 24-hour period.