Organization events are published when organization-level changes occur, such as organization creation, updates, or member management. All organization events are published to the AWS_SNS_TICKET_TOPIC_ARN topic.

​
Event types

​
Organization lifecycle events

​
organization:created

Triggered when a new organization is created. Payload structure: 
{
  organization: {
    id: string;
    name: string;
    domain?: string;
    subdomain: string;
    plan: string;
    status: string;
    settings?: Record<string, unknown>;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
Event context:
  • Triggered during organization setup process
  • May be part of a larger user onboarding flow
  • Often followed by initial configuration events

​
organization:updated

Triggered when an organization’s details are updated. Payload structure: 
{
  organization: OrganizationData;
  previousOrganization: OrganizationData; // Previous state before update
}
Common update scenarios:
  • Plan changes (free to paid, plan upgrades/downgrades)
  • Organization name or domain changes
  • Settings updates (timezone, locale, etc.)
  • Metadata modifications

​
organization:deleted

Triggered when an organization is deleted. Payload structure: 
{
  previousOrganization: OrganizationData; // The deleted organization data
}
Important notes:
  • This is a destructive operation
  • All associated data (tickets, accounts, users) are also affected
  • Consider implementing appropriate cleanup logic

​
Organization membership events

​
organization:member-joined

Triggered when a user joins an organization. Payload structure: 
{
  organization: {
    id: string;
    name: string;
    domain?: string;
    subdomain: string;
    plan: string;
    status: string;
    settings?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
  user: {
    id: string;
    email: string;
    name: string;
    userType: string;
    status: string;
    roles?: string[];
    teams?: Array<{
      id: string;
      name: string;
    }>;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}
Common scenarios:
  • New employee onboarding
  • Contractor or external user access
  • User role changes that affect organization membership
  • Bulk user imports

​
Event structure

All organization events follow the standard SNS event structure: 
interface OrganizationSNSEvent<T> {
  eventId: string;
  eventType: string; // One of the OrganizationEvents enum values
  timestamp: string;
  orgId: string;
  actor: {
    id: string;
    type: string; // Usually "ADMIN" or "OWNER"
    email: string;
  };
  payload: T;
}

​
Special considerations

​
Organization creation flow

When an organization is created, it typically triggers a cascade of events:
  1. organization:created - The organization itself is created
  2. organization:member-joined - The organization creator becomes the first member
  3. Additional setup events (teams, initial configuration)

​
Actor context

For organization events, the actor field represents:
  • Creation: The user creating the organization (may be a system user for automated processes)
  • Updates: The admin or owner making changes
  • Member join: The user being added or the admin adding them
  • Deletion: The admin or owner performing the deletion

​
Integration examples

​
Organization provisioning

function handleOrganizationCreated(payload) {
  const { organization } = payload;
  
  // Provision external resources
  provisionSlackWorkspace(organization);
  createBillingAccount(organization);
  setupInitialTeams(organization);
  
  // Send welcome emails
  sendOrganizationWelcomeEmail(organization);
  
  // Initialize analytics tracking
  trackOrganizationCreated({
    orgId: organization.id,
    plan: organization.plan,
    domain: organization.domain
  });
}

​
Member onboarding

function handleMemberJoined(payload) {
  const { organization, user } = payload;
  
  // Send welcome email with organization context
  sendUserWelcomeEmail(user, organization);
  
  // Provision user in external systems
  createSlackUser(user, organization);
  updateCRMContact(user, organization);
  
  // Set up user permissions
  assignDefaultPermissions(user, organization);
  
  // Track user growth metrics
  trackUserJoined({
    orgId: organization.id,
    userId: user.id,
    userType: user.userType
  });
}

​
Plan change handling

function handleOrganizationUpdated(payload) {
  const { organization, previousOrganization } = payload;
  
  // Check if plan changed
  if (organization.plan !== previousOrganization.plan) {
    handlePlanChange({
      orgId: organization.id,
      previousPlan: previousOrganization.plan,
      newPlan: organization.plan
    });
    
    // Update billing
    updateBillingPlan(organization);
    
    // Adjust feature access
    updateFeatureAccess(organization);
  }
  
  // Check for domain changes
  if (organization.domain !== previousOrganization.domain) {
    updateDNSRecords(organization);
    updateSSLCertificates(organization);
  }
}

​
Organization cleanup

function handleOrganizationDeleted(payload) {
  const { previousOrganization } = payload;
  
  // Clean up external resources
  deprovisionSlackWorkspace(previousOrganization);
  cancelBillingSubscription(previousOrganization);
  
  // Archive data in external systems
  archiveAnalyticsData(previousOrganization.id);
  archiveCRMData(previousOrganization.id);
  
  // Send confirmation emails to admins
  sendDeletionConfirmation(previousOrganization);
  
  // Update metrics
  trackOrganizationDeleted({
    orgId: previousOrganization.id,
    plan: previousOrganization.plan,
    memberCount: previousOrganization.memberCount
  });
}

​
Security considerations

​
Sensitive data

Organization events may contain sensitive information:
  • Billing details in plan changes
  • Domain information that could reveal company structure
  • User email addresses and roles

​
Access control

  • Ensure SNS subscribers have appropriate permissions
  • Consider separate topics for different sensitivity levels
  • Implement proper authentication for webhook endpoints

​
Monitoring and alerting

​
Key metrics to track

  1. Organization growth: Track creation and deletion rates
  2. Plan changes: Monitor upgrade/downgrade patterns
  3. Member growth: Track user addition rates per organization
  4. Churn indicators: Monitor organizations with recent plan downgrades

​
Alert scenarios

// High-value organization deletion
if (organization.plan === 'Enterprise' && eventType === 'organization:deleted') {
  alertSalesTeam(organization);
}

// Rapid member growth (potential abuse)
if (memberJoinedCount > 100 && timeWindow < '1 hour') {
  alertSecurityTeam(organization);
}

// Plan downgrade after recent upgrade
if (planChangePattern === 'upgrade_then_downgrade' && timeWindow < '7 days') {
  alertCustomerSuccess(organization);
}

​
Best practices

  1. Event ordering: Process organization events before related entity events
  2. Idempotency: Use eventId to prevent duplicate processing
  3. Cascading effects: Be prepared for organization events to trigger additional events
  4. Data consistency: Ensure external systems reflect organization state changes
  5. Performance: Organization events can trigger expensive operations, consider async processing

​
Error handling

Common error scenarios and handling strategies: 
function handleOrganizationEventError(event, error) {
  switch (error.type) {
    case 'EXTERNAL_SERVICE_UNAVAILABLE':
      // Retry with exponential backoff
      scheduleRetry(event, { delay: calculateBackoff(event.retryCount) });
      break;
      
    case 'INVALID_ORGANIZATION_STATE':
      // Log and alert, may require manual intervention
      logCriticalError(event, error);
      alertOperationsTeam(event, error);
      break;
      
    case 'RATE_LIMIT_EXCEEDED':
      // Queue for later processing
      queueForLaterProcessing(event, { delay: '5 minutes' });
      break;
      
    default:
      // Generic error handling
      logError(event, error);
      if (event.retryCount < MAX_RETRIES) {
        scheduleRetry(event);
      } else {
        alertDevelopmentTeam(event, error);
      }
  }
}

​
Event frequency

Organization events are typically low-frequency events:
  • Creation: Usually during initial setup or business growth
  • Updates: Periodic configuration changes, plan modifications
  • Member joins: Varies by organization size and growth phase
  • Deletion: Rare, but critical for cleanup processes
However, during bulk operations or migrations, these events can spike significantly.