The Thena platform publishes various events to Amazon SNS (Simple notification service) to enable real-time integrations and webhooks. This documentation provides a comprehensive overview of all available events, their payloads, and metadata.

​
Event categories

The platform publishes events across several categories:
  1. Ticket events - Events related to ticket lifecycle and operations
  2. Account events - Events for account management operations
  3. Organization events - Organization-level events
  4. Comment events - Comment and communication events
  5. User events - User mention and interaction events
  6. Custom object events - Custom object lifecycle events

​
Common event structure

All SNS events follow a common structure with the following properties:

​
Base event schema

interface BaseSNSEvent<T> {
  eventId: string;           // Unique identifier for the event
  eventType: string;         // Event type identifier (e.g., "ticket:created")
  timestamp: string;         // Event timestamp (ISO string or Unix timestamp)
  orgId: string;            // Organization ID
  actor: {                  // User who triggered the event
    id: string;
    type: string;           // User type (e.g., "AGENT", "CUSTOMER")
    email: string;
  };
  payload: T;               // Event-specific payload
  metadata?: Record<string, unknown>; // Optional metadata
}

​
Message attributes

All SNS messages include the following attributes for filtering and routing:
  • event_name - The event type (e.g., “ticket:created”)
  • event_id - Unique event identifier
  • event_timestamp - Event timestamp
  • context_user_id - ID of the user who triggered the event
  • context_user_type - Type of the user (AGENT, CUSTOMER, etc.)
  • context_organization_id - Organization ID

​
Topic configuration

Events are published to different SNS topics based on their type:
  • Most platform events: Published to AWS_SNS_TICKET_TOPIC_ARN (includes ticket, account, organization, comment, and user events)
  • Custom object events: Published to AWS_SNS_CUSTOM_OBJECT_TOPIC_ARN (dedicated topic for custom object lifecycle events)
This separation allows for more granular subscription management, where integrations can choose to subscribe to either core platform events, custom object events, or both depending on their specific requirements.

​
Event delivery

​
Message size limits

All events respect the SNS message size limit of 256KB. If an event payload exceeds this limit, the system automatically truncates large content fields (such as comment content) and replaces them with “Payload too large. Use API instead”.

​
Retry logic

Failed events are automatically retried with exponential backoff. The system distinguishes between:
  • Transient errors: Network issues, timeouts - automatically retried
  • Permanent errors: Not found errors, validation errors - not retried

​
Message grouping

Events use the organization ID as the message group ID to ensure ordering within each organization.

​
Integration examples

​
Webhook integration

// Example webhook handler for ticket events
app.post('/webhook/sns', (req, res) => {
  const message = JSON.parse(req.body.Message);
  
  switch (message.eventType) {
    case 'ticket:created':
      handleTicketCreated(message.payload);
      break;
    case 'ticket:comment:added':
      handleCommentAdded(message.payload);
      break;
    // Handle other events...
  }
  
  res.status(200).send('OK');
});

​
Event filtering

Use SNS message attributes to filter events: 
{
  "FilterPolicy": {
    "event_name": ["ticket:created", "ticket:updated"],
    "context_organization_id": ["org-123"]
  }
}

​
Next steps

  • Explore specific event types in the navigation menu
  • Set up platform subscriptions for your integration needs

​
Support

For questions about our platform events or integration support, please contact our developer support team.