Skip to main content

Events and Webhooks

The DSM includes an event system that records every significant action, an inbound webhook framework for receiving data from external systems, and supporting structures for public-facing identity and trust credentials.

The event system​

Every significant action in the DSM — user creation, data sharing, state changes — is recorded as an event. Events form the platform's audit trail (or "paper trail"), providing a complete, tamper-resistant history of what happened, when, and by whom.

What gets recorded​

Each event captures:

  • A reference — which entity the event relates to (such as a user, node, or instance)
  • A timestamp — when the event occurred
  • An event type — a classification like user_create or aa_submission.created
  • An event payload — the details of what happened, structured as JSON

How events are created and processed​

Events are generated in two ways:

  • Automatic triggers — certain system actions (like user registration) directly create event records
  • Background job processing — most DSM tables generate events through background jobs rather than writing directly to the event table. This ensures consistent formatting, enrichment, and reliable delivery even under load.

Tables that generate paper trail events include nodes (on creation and update) and sharing instances (on update).

Event-driven actions​

Events can trigger downstream actions that extend beyond audit logging:

  • Notifications — sending emails, SMS, or in-app messages to relevant parties
  • Outbound webhooks — delivering event data to external systems via HTTP webhooks
  • Workflow automation — initiating automated processes or state transitions
  • Integrations — propagating changes to connected systems and third-party services

These actions allow the DSM to serve as an event-driven engine that keeps external systems in sync and enables complex multi-party workflows.

Access control​

Event records are protected from tampering. Regular users can read events they own and create new events, but only administrative users can update or delete event records. This prevents users from altering their own audit trail.

Inbound webhooks​

The inbound webhook system allows external platforms to push data into an access application. Each webhook subscription defines the complete pipeline for receiving, validating, and processing incoming data.

Processing pipeline​

When an external system sends a webhook, the data flows through several stages:

  1. Signature verification — if enabled, the system validates the provider's cryptographic signature to confirm the webhook is authentic
  2. Filter evaluation — the incoming payload is checked against a filter schema to determine whether it should be processed
  3. Field mapping — the payload is transformed according to a mapping schema, converting external field names and structures into DSM-compatible formats
  4. Action execution — the mapped data triggers the configured action (such as creating or updating an instance)
  5. Logging — every webhook interaction is logged with full request and response details

Webhook logs​

Each webhook invocation is recorded with the incoming request headers and payload, the response sent back, the HTTP status code, and the processing outcome. This log enables debugging webhook integrations and provides evidence of data provenance — knowing exactly what data was received, from which external system, and when.

Access control​

Webhook configurations inherit access from their parent access application. Only application owners and editors can create or modify webhook subscriptions, ensuring that external data flows are controlled by the people responsible for the application.