Account events are published whenever accounts, customer contacts, or account-related entities (activities, notes, tasks, relationships) are created, updated, or deleted. All account events are published to the AWS_SNS_TICKET_TOPIC_ARN topic.

Core account events

Account lifecycle

account:created

Triggered when a new account is created. Payload structure:
{
  account: {
    id: string;
    name: string;
    domain?: string;
    industry?: string;
    size?: string;
    status: string;
    health: string;
    classification: string;
    metadata?: Record<string, unknown>;
    customFields?: Record<string, string[]>;
    createdAt: Date;
    updatedAt: Date;
  };
}

account:updated

Triggered when an account is updated. Payload structure:
{
  account: AccountData;
  previousAccount: AccountData; // Previous state
}

account:deleted

Triggered when an account is deleted. Payload structure:
{
  previousAccount: AccountData; // The deleted account data
}

Account attribute change events

These events are triggered when specific account attributes change:

account-health:changed

Triggered when an account’s health status changes.

account-status:changed

Triggered when an account’s status changes.

account-classification:changed

Triggered when an account’s classification changes.

account-industry:changed

Triggered when an account’s industry changes.

Account custom field events

account-custom_field_value:added

Triggered when a custom field value is added to an account. Additional payload:
{
  changedCustomFields: Array<{
    fieldUid: string;
    newValues: string[];
    changeType: "added";
  }>;
}

account-custom_field_value:removed

Triggered when a custom field value is removed from an account. Additional payload:
{
  changedCustomFields: Array<{
    fieldUid: string;
    previousValues: string[];
    changeType: "removed";
  }>;
}

account-custom_field_value:changed

Triggered when a custom field value is changed on an account. Additional payload:
{
  changedCustomFields: Array<{
    fieldUid: string;
    previousValues: string[];
    newValues: string[];
    changeType: "updated";
  }>;
}

Customer contact events

Customer contact lifecycle

customer-contact:created

Triggered when a new customer contact is created. Payload structure:
{
  customerContact: {
    id: string;
    firstName: string;
    lastName: string;
    email: string;
    phone?: string;
    jobTitle?: string;
    type: string;
    status: string;
    accountId: string;
    metadata?: Record<string, unknown>;
    customFields?: Record<string, string[]>;
    createdAt: Date;
    updatedAt: Date;
  };
}

customer-contact:updated

Triggered when a customer contact is updated. Payload structure:
{
  customerContact: CustomerContactData;
  previousCustomerContact: CustomerContactData;
}

customer-contact:deleted

Triggered when a customer contact is deleted. Payload structure:
{
  previousCustomerContact: CustomerContactData;
}

customer-contact:type:changed

Triggered when a customer contact’s type changes.

Customer contact custom field events

customer-contact:custom_field_value:added

Triggered when a custom field value is added to a customer contact.

customer-contact:custom_field_value:removed

Triggered when a custom field value is removed from a customer contact.

customer-contact:custom_field_value:changed

Triggered when a custom field value is changed on a customer contact.

Account relationship events

Account relationship lifecycle

account-relationship:created

Triggered when a new account relationship is created. Payload structure:
{
  relationship: {
    id: string;
    parentAccountId: string;
    childAccountId: string;
    relationshipType: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}

account-relationship:updated

Triggered when an account relationship is updated. Payload structure:
{
  relationship: AccountRelationshipData;
  previousRelationship: AccountRelationshipData;
}

account-relationship:deleted

Triggered when an account relationship is deleted. Payload structure:
{
  previousRelationship: AccountRelationshipData;
}

Account activity events

Account activity lifecycle

account-activity:created

Triggered when a new account activity is created. Payload structure:
{
  activity: {
    id: string;
    accountId: string;
    title: string;
    description?: string;
    activityType: string;
    status: string;
    scheduledAt?: Date;
    completedAt?: Date;
    assignedUserId?: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}

account-activity:updated

Triggered when an account activity is updated. Payload structure:
{
  activity: AccountActivityData;
  previousActivity: AccountActivityData;
}

account-activity:deleted

Triggered when an account activity is deleted. Payload structure:
{
  previousActivity: AccountActivityData;
}

Account activity comment events

account-activity:comment:created

Triggered when a comment is added to an account activity.

account-activity:comment:updated

Triggered when a comment on an account activity is updated.

account-activity:comment:deleted

Triggered when a comment is deleted from an account activity.

Account note events

Account note lifecycle

account-note:created

Triggered when a new account note is created. Payload structure:
{
  note: {
    id: string;
    accountId: string;
    title: string;
    content: string;
    visibility: string;
    authorId: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}

account-note:updated

Triggered when an account note is updated. Payload structure:
{
  note: AccountNoteData;
  previousNote: AccountNoteData;
}

account-note:deleted

Triggered when an account note is deleted. Payload structure:
{
  previousNote: AccountNoteData;
}

Account note comment events

account-note:comment:created

Triggered when a comment is added to an account note.

account-note:comment:updated

Triggered when a comment on an account note is updated.

account-note:comment:deleted

Triggered when a comment is deleted from an account note.

Account task events

Account task lifecycle

account-task:created

Triggered when a new account task is created. Payload structure:
{
  task: {
    id: string;
    accountId: string;
    title: string;
    description?: string;
    status: string;
    priority: string;
    dueDate?: Date;
    assignedUserId?: string;
    metadata?: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
  };
}

account-task:updated

Triggered when an account task is updated. Payload structure:
{
  task: AccountTaskData;
  previousTask: AccountTaskData;
}

account-task:deleted

Triggered when an account task is deleted. Payload structure:
{
  previousTask: AccountTaskData;
}

Account task comment events

account-task:comment:created

Triggered when a comment is added to an account task.

account-task:comment:updated

Triggered when a comment on an account task is updated.

account-task:comment:deleted

Triggered when a comment is deleted from an account task.

Event structure

All account events follow the standard SNS event structure:
interface AccountSNSEvent<T> {
  eventId: string;
  eventType: string; // One of the AccountEvents enum values
  timestamp: string;
  orgId: string;
  actor: {
    id: string;
    type: string;
    email: string;
  };
  payload: T;
}

Integration examples

Account health monitoring

function handleAccountHealthChange(payload) {
  const { account, previousAccount } = payload;
  
  if (account.health === 'At Risk' && previousAccount.health !== 'At Risk') {
    // Account became at risk
    triggerAccountReview(account.id);
    notifyAccountManager(account.id);
  } else if (account.health === 'Healthy' && previousAccount.health === 'At Risk') {
    // Account recovered
    logAccountRecovery(account.id);
  }
}

Customer contact synchronization

function handleContactCreated(payload) {
  const { customerContact } = payload;
  
  // Sync to CRM
  syncToCRM({
    type: 'contact',
    id: customerContact.id,
    email: customerContact.email,
    name: `${customerContact.firstName} ${customerContact.lastName}`,
    accountId: customerContact.accountId
  });
  
  // Update marketing lists
  updateMarketingSegmentation(customerContact);
}

Task management integration

function handleTaskCreated(payload) {
  const { task } = payload;
  
  if (task.priority === 'High' && task.dueDate) {
    // Create calendar reminder
    createCalendarEvent({
      title: task.title,
      date: task.dueDate,
      assignee: task.assignedUserId
    });
  }
  
  // Update project management tool
  syncToProjectManagement(task);
}

Best practices

  1. Account hierarchy: Use relationship events to maintain account hierarchies in external systems
  2. Data consistency: Process events in order using the timestamp to maintain data consistency
  3. Bulk operations: Be prepared for high-volume events during bulk imports or updates
  4. Custom fields: Monitor custom field events for account scoring and segmentation
  5. Activity tracking: Use activity events to build comprehensive account timelines

Event frequency

Account events have moderate frequency but can spike during:
  • Bulk imports
  • Account health reassessments
  • Custom field updates
  • Integration synchronizations
Consider implementing appropriate rate limiting and queuing strategies for downstream processing.