Docs

Set Up Webhooks

Configure webhooks to receive real-time notifications when objects change state.

8 minBeginner

Prerequisites

  • A DUAL account
  • A publicly accessible HTTPS endpoint

What You'll Build

Webhooks let your server receive real-time HTTP callbacks when events occur in DUAL — like object transfers, property changes, or new mints. In this tutorial you'll register a webhook endpoint, configure event filters, and handle incoming payloads.

Step 1 — Create Your Endpoint

Set up an HTTPS endpoint on your server that accepts POST requests. Here's a minimal Node.js example:

javascript
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/dual', (req, res) => {
  const event = req.body;
  console.log('Event:', event.event_type);
  console.log('Object:', event.object_id);
  console.log('Data:', event.payload);

  // Always return 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook server on :3000'));

Step 2 — Register the Webhook

Tell DUAL to send events to your endpoint:

bash
curl -X POST https://blockv-labs.io/webhooks \
  -H "Authorization: Bearer $DUAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "url": "https://your-server.com/webhooks/dual",
      "events": ["object.transferred", "object.updated"],
      "active": true
    }
  }'

Step 3 — Test with a Transfer

Transfer an object to trigger a webhook delivery:

bash
curl -X POST https://blockv-labs.io/ebus/events \
  -H "Authorization: Bearer $DUAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "Transfer",
    "object_id": "your-object-id",
    "new_owner": "recipient-wallet"
  }'

Within seconds your endpoint should receive a POST with a payload like:

json
{
  "event_type": "object.transferred",
  "object_id": "abc-123",
  "timestamp": "2026-03-13T10:30:00Z",
  "payload": {
    "previous_owner": "wallet-a",
    "new_owner": "wallet-b"
  }
}

Step 4 — Manage Your Webhooks

List all registered webhooks:

bash
curl https://blockv-labs.io/webhooks \
  -H "Authorization: Bearer $DUAL_TOKEN"

Delete a webhook by ID:

bash
curl -X DELETE https://blockv-labs.io/webhooks/{webhookId} \
  -H "Authorization: Bearer $DUAL_TOKEN"
Retry Policy: DUAL retries failed webhook deliveries with exponential backoff (1s, 5s, 30s, 5m). After 5 consecutive failures, the webhook is automatically deactivated. Re-enable it via PATCH /webhooks/{id}.

What's Next?

Ready to add monetization? Head to Integrate Payments.

Build a Web FaceIntegrate Payments