Skip to content
WebsiteDocumentationDashboard ↗LibertyJS repo ↗npm package ↗GitHub organization ↗

LibertyTools / Docs

Events and credentials

An event is a record of something ER:LC reported. This page shows the shape your Poll client or Signed Proxy handler can expect and explains which credential belongs in each place.

Example event

When a player runs ;help, a normalized CustomCommand event can look like this. The values below are fake examples:

{
  "id": "evt_example",
  "connectionId": "con_example",
  "type": "CustomCommand",
  "occurredAt": "2026-10-16T14:21:47.000Z",
  "receivedAt": "2026-10-16T14:21:47.783Z",
  "serverId": "123456",
  "data": {
    "userId": "98765",
    "command": "help",
    "argument": ""
  },
  "synthetic": false
}

occurredAt is when ER:LC says it happened; receivedAt is when LibertyTools accepted it. data contains fields specific to the event type. A test event created in the dashboard is marked synthetic: true and does not run a live ER:LC command.

Required and optional fields

  • id, connectionId, type, occurredAt, receivedAt, data, and synthetic are included on normalized events.
  • serverId is optional. Treat it as an opaque string, not necessarily a numeric Roblox ID.
  • originalType may preserve the source event name. Unrecognized source types become Unknown; inspect originalType when available.
  • For CustomCommand, data.command is lowercase without the leading semicolon. It, data.argument, and data.userId are strings; missing source values become empty strings. Validate the player ID before replying.
  • data.username is optional and only present when supplied by the source.

Other types have different data. A WebhookProbe is a connection check, not a player command. Poll backlog state belongs to the response envelope, not a pollState property on events. This normalized format is used by v2 Poll and Signed Proxy; Exact ER:LC copy preserves the original request instead.

Which credential goes where?

ValuePurposeWhere to use it
ER:LC webhook URLReceive eventsYour ER:LC server's Event Webhook setting
Poll tokenRead a subscription's eventsPrivate server-side bot environment
ER:LC server keySend ER:LC commandsDashboard Settings or private bot environment
Forward signing secretVerify Signed Proxy requestsYour receiver's private server environment

The ingest URL alone does not authorize Poll reads. Never place private credentials in a browser, public repository, or AI prompt.

Limits and retention

  • Poll: 5,000 pending events per subscription and 14-day pending expiry. Oldest pending events are dropped first.
  • Poll reads: 120 per minute per subscription. A 429 response means wait before retrying.
  • Event storage: a 100 MiB accounted event-data budget per connection. Oldest events can be removed, including events with pending work; losses are shown in the dashboard.
  • Forwarding: a bounded queue per destination. Attempts stop after 30 minutes. The dashboard shows queue depth, failures, and dropped work.
  • Hosted commands: LibertyTools limits remote commands and announcements to protect the ER:LC API. Unsent commands wait for capacity and expire after five minutes; rejected or uncertain command results are not automatically replayed. Check Recent command runs for the result of a specific action.

Actual database storage can exceed the accounted event-data budget because of indexes and database overhead. If you were offline, check dropped counts when reconnecting instead of assuming every event is still available.