Dregs
Manual

Events

Every action a user takes in your application becomes an event in Dregs — a complete audit trail that feeds real-time scoring. Events are the raw material that powers behavioral analysis, and the more you send, the sharper the picture becomes.

What Are Events

An event is a discrete record of something a user did. Dregs handles two types of events:

  • Identify events — created when you call dregs.identify() to associate the current device with a user identity. This is how Dregs learns who is behind a device.
  • Custom events — created when you call dregs.track() to record a specific action. These are the behavioral building blocks: signups, logins, purchases, form submissions, and anything else worth tracking.

Both types are stored as events, but they serve different roles. Identify events establish the device-to-identity mapping. Custom events provide the behavioral data that feeds scoring.

What Events Capture

Every event automatically includes a rich set of contextual data, without any extra work on your part:

  • Event type — the name you give the event (e.g., "signup", "purchase")
  • Custom data — any key-value pairs you choose to include
  • Identity — the user ID, if one has been identified on this device
  • Device fingerprint — the full fingerprint of the device that generated the event
  • IP address — the network address, geolocated to city and country
  • URL — the page where the event occurred
  • Timestamp — server-side timestamp for reliable ordering

You decide the event type and custom data. Everything else is collected automatically by the tracking script and the Dregs backend.

Sending Events

Events are sent through the tracking script on your frontend, or via the REST API from your backend. The two primary frontend methods are: 

// Associate this device with a user identity
dregs.identify("user-123");

// Track a custom event with optional data
dregs.track("purchase", {
  plan: "pro",
  amount: 49.99,
  currency: "USD"
});

The types of events worth tracking depend on your application, but these are commonly valuable:

  • signup — account creation, the most important single event for fraud detection
  • login — session starts, useful for detecting credential stuffing and account takeover
  • purchase — transactions, critical for payment fraud patterns
  • form_submit — form completions, useful for detecting automated submissions
  • password_change — security-sensitive actions that may indicate account compromise
  • profile_update — data changes, useful for detecting identity manipulation
  • feature_usage — application interactions, builds the behavioral baseline

There is no limit on event types. Create as many as are meaningful for your application. See the Tracking page for the full API reference, including backend event tracking via the REST API.

Frontend and Backend Events

Events can come from two sources: the frontend tracking script running in the browser, and your backend server via the REST API. Dregs stitches them together by identity ID, so a single identity has a unified timeline of both browser-side and server-side activity.

Frontend events automatically include device fingerprints and browser context. Backend events enrich the profile with server-verified data like payment history, administrative actions, and API activity that the browser never sees.

See the Tracking page for complete details on both frontend and backend event tracking, including the API payload format and identity stitching.

How Events Feed Scoring

Events are the raw material for the entire scoring system. When new events arrive for an identity, Dregs re-runs its analyzers to update scores. Here is how events contribute to each dimension:

  • Humanity — analyzers examine event timing intervals. Human actions have natural variation; automated scripts produce unnaturally uniform or rapid-fire patterns.
  • Authenticity — the data submitted in events (names, emails, profile fields) is checked for consistency and plausibility.
  • Uniqueness — events establish device-identity relationships. When multiple identities generate events from the same device, Uniqueness scores adjust.
  • Behavior — session frequency, time-of-day patterns, IP address changes, and navigation sequences all come from event data.

More events mean higher confidence in scores. A user with three events will have a preliminary score. A user with three hundred events will have a score you can act on with high confidence.

The Event Stream

The Events page in the dashboard displays a real-time feed of all events flowing into your account. You can filter the stream by:

  • Identity — show events for a specific user
  • Device — show events from a specific device fingerprint
  • Free text search — search across event names, IP addresses, and identity IDs

The event stream is your primary tool for investigating specific users or incidents. When an alert fires, the event stream lets you see exactly what the user did leading up to it.

Event Data

The second argument to dregs.track() is a plain object of custom key-value pairs. This data is stored with the event and displayed in the dashboard, giving you context about what happened.

A few keys are reserved by Dregs and should not be overwritten:

  • _u — the page URL (set automatically)
  • _i — the identity ID (set automatically)
  • _o — the organization (set automatically if configured)
  • _e — error information (set automatically on failures)

Any key starting with an underscore is treated as a system field. Avoid underscore prefixes for your own data to prevent conflicts.

Privacy Considerations

Dregs automatically redacts underscore-prefixed fields from API responses, ensuring that internal system data is not inadvertently exposed. For your own custom data, apply the same principle you would to any audit log: only send data you have legitimate reason to process, and that your users have consented to where required.

Event data is scoped to your account and never shared across customers. Only authenticated users on your team (or your own backend via API credentials) can access your event data.

← Scoring
Dashboard →