Events

Events provide a complete audit trail of all activities in Crane Ledger. Every transaction, update, and system action is recorded as an event, providing full traceability and compliance capabilities.

The Event Object

GET/events/:entity_type/:entity_id

Auth required

{
  "id": "evt_xxxxxxxxxxxxxxxx",
  "object": "event",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "entity_type": "transaction",
  "entity_id": "txn_xxxxxxxxxxxxxxxx",
  "event_type": "transaction.created",
  "description": "Transaction posted to general ledger",
  "user_id": "usr_xxxxxxxxxxxxxxxx",
  "api_key_id": "key_xxxxxxxxxxxxxxxx",
  "ip_address": "192.168.1.100",
  "user_agent": "CraneLedger/1.0",
  "metadata": {
    "amount": "500.00",
    "account_id": "act_xxxxxxxxxxxxxxxx"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `evt_` prefix
`organization_id`	string	The organization this event belongs to
`entity_type`	enum	Type of entity (`transaction`, `invoice`, `account`, etc.)
`entity_id`	string	ID of the affected entity
`event_type`	string	Specific event type (e.g., `transaction.created`)
`description`	string	Human-readable description
`user_id`	string	User who triggered the event (if applicable)
`api_key_id`	string	API key used for the request
`ip_address`	string	IP address of the request
`user_agent`	string	User agent string
`metadata`	object	Additional event-specific data
`created_at`	datetime	When the event occurred

List Events

GET/organizations/:organization_id/events

Auth required

Returns a paginated list of events for the organization.

Path Parameters

Parameter	Type	Required	Description
`organization_id`	string	Yes	The organization ID

Query Parameters

Parameter	Type	Description
`entity_type`	enum	Filter by entity type
`entity_id`	string	Filter by specific entity
`event_type`	string	Filter by event type
`user_id`	string	Filter by user
`api_key_id`	string	Filter by API key
`from_date`	datetime	Start date for events
`to_date`	datetime	End date for events
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset

Response

{
  "object": "list",
  "data": [
    {
      "id": "evt_xxxxxxxxxxxxxxxx",
      "entity_type": "transaction",
      "entity_id": "txn_xxxxxxxxxxxxxxxx",
      "event_type": "transaction.created",
      "description": "Transaction posted to general ledger",
      "user_id": "usr_xxxxxxxxxxxxxxxx",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "evt_yyyyyyyyyyyyyyyy",
      "entity_type": "invoice",
      "entity_id": "inv_xxxxxxxxxxxxxxxx",
      "event_type": "invoice.sent",
      "description": "Invoice sent to customer",
      "api_key_id": "key_xxxxxxxxxxxxxxxx",
      "created_at": "2024-01-15T14:20:00Z"
    }
  ],
  "has_more": true,
  "total_count": 150
}

Get Entity Events

GET/events/:entity_type/:entity_id

Auth required

Returns all events related to a specific entity (transaction, invoice, account, etc.).

Path Parameters

Parameter	Type	Required	Description
`entity_type`	string	Yes	Type of entity (`transaction`, `invoice`, `account`, etc.)
`entity_id`	string	Yes	The entity ID

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default: 20, max: 100)
`offset`	integer	Pagination offset

Response

{
  "object": "list",
  "entity_type": "transaction",
  "entity_id": "txn_xxxxxxxxxxxxxxxx",
  "data": [
    {
      "id": "evt_xxxxxxxxxxxxxxxx",
      "event_type": "transaction.created",
      "description": "Transaction created",
      "user_id": "usr_xxxxxxxxxxxxxxxx",
      "created_at": "2024-01-15T10:25:00Z"
    },
    {
      "id": "evt_yyyyyyyyyyyyyyyy",
      "event_type": "transaction.posted",
      "description": "Transaction posted to general ledger",
      "user_id": "usr_xxxxxxxxxxxxxxxx",
      "metadata": {
        "debit_entries": 2,
        "credit_entries": 2,
        "total_amount": "1250.00"
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": false,
  "total_count": 2
}

Event Types

Transaction Events

transaction.created - Transaction initially created
transaction.updated - Transaction modified
transaction.posted - Transaction posted to ledger
transaction.reversed - Transaction reversed
transaction.deleted - Transaction deleted

Invoice Events

invoice.created - Invoice created
invoice.updated - Invoice modified
invoice.sent - Invoice marked as sent
invoice.viewed - Invoice viewed by customer
invoice.payment_received - Payment recorded
invoice.paid - Invoice fully paid
invoice.cancelled - Invoice cancelled
invoice.deleted - Invoice deleted

Account Events

account.created - Account created
account.updated - Account modified
account.deleted - Account deleted

Contact Events

contact.created - Contact created
contact.updated - Contact modified
contact.deleted - Contact deleted

API Key Events

api_key.created - API key created
api_key.updated - API key modified
api_key.rotated - API key rotated
api_key.revoked - API key revoked

System Events

organization.created - Organization created
user.invited - User invited to organization
settings.updated - Organization settings changed

Event Metadata

Events include contextual metadata depending on the event type:

Transaction Events

{
  "amount": "500.00",
  "currency": "USD",
  "debit_entries": 2,
  "credit_entries": 2,
  "description": "Office supplies purchase"
}

Invoice Events

{
  "invoice_number": "INV-2024-001",
  "amount": "1250.00",
  "customer_id": "con_xxxxxxxxxxxxxxxx",
  "due_date": "2024-02-14"
}

Payment Events

{
  "payment_amount": "1250.00",
  "payment_date": "2024-01-20",
  "payment_method": "check",
  "reference": "CHK-12345"
}

Audit Trail Best Practices

Compliance Requirements

Maintain events for regulatory retention periods
Implement automated archival for old events
Secure event data against unauthorized modification
Provide audit reports for compliance reviews

Monitoring and Alerts

Set up alerts for unusual activity patterns
Monitor API key usage and failed authentication
Track configuration changes and sensitive operations
Generate regular audit reports

Performance Considerations

Events are append-only for data integrity
Use appropriate indexing for common query patterns
Implement pagination for large result sets
Consider event aggregation for high-volume operations

Data Retention

Retain events for minimum regulatory periods
Implement automated cleanup policies
Archive old events to separate storage
Maintain backup copies for disaster recovery

Security Measures

Encrypt sensitive data in event metadata
Implement access controls for event viewing
Log access to audit trails themselves
Use tamper-proof storage mechanisms

Event Immutability

Events are immutable once created. They cannot be modified or deleted to ensure the integrity of the audit trail. This is critical for regulatory compliance and forensic analysis.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference