Custom events

Custom events are facts your application understands: checkout failed, intake submitted, a patient alarm fired. They are not browser console.* output and they are not the mixed Events stream of clicks, pointer moves, and requests.

Record them with Backstory.track(). They show up in the Custom events panel on recorded sessions and Live Assist, can promote a buffered session to storage, and can fire notification rules.

Record an event

Backstory.track("intake_form_submitted", { steps: 4 });
Backstory.track(
  "checkout_failed",
  { reason: "card_declined", orderId: "ord_123" },
  { severity: "error" },
);

Argument	Type	Notes
name	string	Stable identifier. Use snake_case or dotted names (checkout.failed).
props	Record<string, unknown>	Optional structured context. Recorded as supplied.
options.severity	"debug" | "info" | "warn" | "error"	Optional. Defaults to info.

Existing two-argument calls stay valid. Severity is stored on the event itself, not inside props.

Where they appear

In both recorded sessions and Live Assist, open the DevTools dock and choose Custom events (next to Events).

The panel lists name, severity, properties, and timestamp. Filter by severity (error, warn, info, debug) or search name and properties. Click a row to seek replay to that moment.

The mixed Events tab stays for clicks, pages, errors, console, network, and inputs. Internal SDK events named backstory.* (sampling decisions, monitor bursts, diagnostics) are hidden from Custom events.

Severity

Severity	Typical use	Notification mapping
debug	High-volume diagnostic breadcrumbs	low
info	Expected business milestones (default)	medium
warn	Recoverable failures, retries, degraded paths	high
error	Failures you would page on	critical

Use severity to tell diagnosis and alerting apart from console logging. A console.error is still browser noise; Backstory.track("checkout_failed", …, { severity: "error" }) is a product fact.

Alerts

Under Notifications → Rules, create a rule with source custom. Match on event name and optional required properties (key=value per line). The rule’s minimum severity uses the mapped values above, so an error event satisfies a high-severity rule.

The webhook type is custom. The payload includes the event name, properties, session link, and severity. See Webhooks.

Recording triggers

In conditional or triggers-only mode, add custom:<name> to the SDK sampling triggers so that event promotes the buffered session:

Backstory.init({
  projectKey: "pk_live_…",
  recording: {
    sampling: {
      mode: "conditional",
      triggers: ["error", "custom:checkout_failed"],
    },
  },
});

In monitor mode, the same name starts a burst with the 60-second pre-roll. Pass severity independently; a trigger fires on the name, not the severity.

Backstory.track("patient_alarm", { bed: 12 }, { severity: "error" });

Privacy

Properties are captured as you pass them. Never include passwords, tokens, payment data, or PHI. Masking that applies to the DOM does not rewrite your props object. Prefer identifiers and codes (orderId, reason) over free-text that could contain personal data.

Backstory.identify(id, name) is the place for the end-user identifier and the person’s display name; both are stored exactly as you send them, so sessions can be attributed to a person.