Dark Matter Docs

What you will build

You will create a webhook endpoint, configure it in DMTR, receive real-time events, and verify request signatures. This quickstart gets you from zero to a working webhook integration.

Prerequisites

A publicly accessible HTTPS endpoint (or ngrok for local development)
API key with webhooks:manage scope
Ability to run a simple HTTP server or use a serverless function

Create a webhook in the DMTR dashboard or via POST /webhooks with your endpoint URL and the event types you want to receive (e.g., position.updated, transfer.settled). Copy the webhook signing secret; you will need it for verification.

Receive events

When events occur, DMTR sends POST requests to your URL with a JSON body containing type, id, created_at, and data. Your endpoint should return 2xx quickly to acknowledge receipt. Process the payload asynchronously to avoid timeouts.

transfer.settled

Fired when a transfer settles and the registry is updated.

Field	Type	Description
type	string	transfer.settled
event_id	string	Unique event ID
timestamp	datetime	When the event occurred
payload.transfer_id	string	Transfer ID
payload.seller_position_id	string	Seller's position entity_id
payload.buyer_position_id	string	Buyer's new position entity_id
payload.escrow_id	string	Escrow reference for DVP settlement
event_hash	string	SHA-256 hash of this event in the hash chain

Verify signatures

Each request includes X-DMTR-Signature. Compute HMAC-SHA256 of the raw request body using your webhook secret; compare with the header value using constant-time comparison. Reject requests with invalid signatures to prevent spoofing.

app.post('/webhooks/dmtr', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-dmtr-signature'];
if (!verifyWebhook(req.body, sig, WEBHOOK_SECRET)) {
  return res.status(401).send('Invalid signature');
}
const event = JSON.parse(req.body);
console.log('Received:', event.type, event.id);
res.status(200).send('OK');
});

Next steps

Webhooks — Full webhook documentation
Go-Live Checklist — Production readiness
Execute Transfer Intent — Transfer workflow

Webhook Quickstart