Dark Matter Docs

Webhook events, signing and verification, delivery guarantees, retry policy, failure handling, and testing.

Overview

Webhooks deliver real-time event notifications to your endpoint when resources change. Configure webhook URLs in the dashboard, subscribe to event types, and verify signatures to ensure authenticity.

Webhook events

Subscribe to events by category. The full list of event types is documented in Event Schemas. Key categories:

Position lifecycle: position.registered, position.updated, position.mark_updated, position.transferred, position.split, position.encumbered, position.encumbrance_released, position.exited, position.voided
Transfer: transfer.evaluated, transfer.consent_requested, transfer.consent_granted, transfer.consent_denied, transfer.settled, transfer.rejected, transfer.payment_funded, transfer.payment_released
IOI: ioi.created, ioi.accepted, ioi.cancelled
Document lifecycle: document.generated, document.sent_for_signature, document.signed, document.voided
Identity: identity.kyc_verified, identity.aml_screened, identity.accreditation_verified, identity.itar_determined
Entity: entity.formed, entity.ein_assigned, entity.dissolved
Filing: filing.form_d_submitted, filing.blue_sky_submitted
Collateral: collateral.pool_created, collateral.position_pledged, collateral.position_released, collateral.margin_call

Each event payload includes event_id, type, actor, timestamp, and payload (the event-specific data). Events also carry hash chain fields (event_hash, previous_event_hash, sequence_number) for audit integrity.

position.updated

Fired when any field on a Position Object changes.

Field	Type	Description
type	string	position.updated
event_id	string	Unique event identifier
timestamp	datetime	ISO 8601 timestamp of event creation
payload.entity_id	string	Position entity ID that changed
payload.changes	object	Field-level diff of the update
actor	string	Entity that triggered the change
event_hash	string	SHA-256 hash of this event in the hash chain

Signing and verification

Each webhook request includes a X-DMTR-Signature header with an HMAC signature of the raw body. Verify the signature using your webhook secret and the request body; reject requests with invalid signatures. Use constant-time comparison to prevent timing attacks.

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Delivery guarantees

Webhooks are delivered at least once; under failure conditions, retries may result in duplicate deliveries. Process events idempotently using the event id. Ordering is best-effort within a resource; do not assume strict ordering across resources.

Retry policy

Failed deliveries (non-2xx response, timeout, connection error) are retried with exponential backoff. Retry schedule and maximum attempts are documented in the webhook configuration. Return 2xx quickly to acknowledge receipt; process asynchronously if needed.

Failure handling

If your endpoint consistently fails, webhooks may be disabled after the retry limit. Monitor webhook delivery status in the dashboard. Implement health checks and alerting for your endpoint. Use the webhook testing tool to validate your implementation before going live.

Testing webhooks

Use the dashboard or API to send test events to your endpoint. Test signature verification, idempotency handling, and error responses. The sandbox environment supports webhook testing with test event payloads.

Webhooks