View a markdown version of this page

Events - Innovation Sandbox on AWS
Consuming eventsEvent structureEvent categoriesLease lifecycle eventsLease monitoring eventsLease assignment eventsAccount management eventsCost reporting eventsBlueprint deployment eventsSchema evolution

Events

Innovation Sandbox publishes domain events to a dedicated Amazon EventBridge event bus (<namespace>-ISBEventBus). You can use these events for audit trails, custom automation, or integration with external systems.

Consuming events

To consume events from the ISB event bus, create an Amazon EventBridge rule that matches the event patterns you are interested in. Common targets include:

  • An Amazon SNS topic for notifications

  • An AWS Lambda function for custom automation

  • An Amazon SQS queue for reliable downstream processing

  • Amazon CloudWatch Logs for audit archival

Event structure

All Innovation Sandbox events follow this standard EventBridge structure:

{
  "version": "0",
  "id": "event-id",
  "detail-type": "EventDetailType",
  "source": "innovation-sandbox",
  "account": "123456789012",
  "time": "2024-01-15T14:30:25Z",
  "region": "us-east-1",
  "detail": {
    // Event-specific payload (documented below)
  }
}

Event categories

Events are organized into the following categories:

  • Lease Lifecycle Events - Lease creation, approval, denial, and termination

  • Lease Monitoring Events - Budget and duration threshold alerts

  • Lease Assignment Events - Requests to share a lease, and confirmed access grants and removals

  • Account Management Events - Account cleanup, drift detection, and account quarantine (automatic and manual)

  • Cost Reporting Events - Cost report generation and failures

  • Blueprint Deployment Events - Blueprint deployment requests, successes, and failures

Lease lifecycle events

LeaseRequested

Published when a user submits a new lease request.

Detail Type: LeaseRequested

Schema: 

{
  "detail-type": "LeaseRequested",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "comments": "Need AWS environment for ML experimentation",
    "userEmail": "developer@example.com",
    "requiresManualApproval": true
  }
}

LeaseApproved

Published when a lease request is approved and the user gains access to their sandbox account.

Detail Type: LeaseApproved

Schema: 

{
  "detail-type": "LeaseApproved",
  "detail": {
    "leaseId": "550e8400-e29b-41d4-a716-446655440000",
    "approvedBy": "manager@example.com",
    "userEmail": "developer@example.com"
  }
}

LeaseDenied

Published when a lease request is denied by an approver.

Detail Type: LeaseDenied

Schema: 

{
  "detail-type": "LeaseDenied",
  "detail": {
    "leaseId": "550e8400-e29b-41d4-a716-446655440000",
    "deniedBy": "manager@example.com",
    "userEmail": "developer@example.com"
  }
}

LeaseTerminated

Published when a lease is terminated for any reason. The reason field provides specific details about why the lease was terminated.

Detail Type: LeaseTerminated

Schema: 

{
  "detail-type": "LeaseTerminated",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "budget": 100.00,
      "totalSpend": 105.50
    }
  }
}

Reason Types: Expired, BudgetExceeded, ManuallyTerminated, UserTerminated, AccountQuarantined, Ejected, ProvisioningFailed

UserTerminated indicates that the leaseholder terminated their own lease; ManuallyTerminated indicates termination by an administrator or manager.

Lease monitoring events

LeaseBudgetThresholdAlert

Published when a lease’s spending reaches a configured budget threshold percentage.

Detail Type: LeaseBudgetThresholdAlert

Schema: 

{
  "detail-type": "LeaseBudgetThresholdAlert",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "budget": 100.00,
    "totalSpend": 80.00,
    "budgetThresholdTriggered": 0.8,
    "actionRequested": "ALERT"
  }
}

LeaseBudgetExceeded

Published when a lease’s spending exceeds the configured budget limit.

Detail Type: LeaseBudgetExceeded

Schema: 

{
  "detail-type": "LeaseBudgetExceeded",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "budget": 100.00,
    "totalSpend": 105.50
  }
}

LeaseDurationThresholdAlert

Published when a lease reaches a configured duration threshold.

Detail Type: LeaseDurationThresholdAlert

Schema: 

{
  "detail-type": "LeaseDurationThresholdAlert",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "triggeredDurationThreshold": 24,
    "leaseDurationInHours": 168,
    "actionRequested": "ALERT"
  }
}

LeaseFreezingThresholdAlert

Published when a lease reaches a threshold that triggers a freezing action. This event uses the same schema as LeaseFrozen.

Detail Type: LeaseFreezingThresholdAlert

Schema: 

{
  "detail-type": "LeaseFreezingThresholdAlert",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "triggeredBudgetThreshold": 0.95,
      "budget": 100.00,
      "totalSpend": 95.00
    }
  }
}

LeaseExpired

Published when a lease expires due to reaching its maximum duration.

Detail Type: LeaseExpired

Schema: 

{
  "detail-type": "LeaseExpired",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "leaseExpirationDate": "2024-01-22T14:30:25Z"
  }
}

LeaseFrozen

Published when a lease is frozen (access suspended but not terminated).

Detail Type: LeaseFrozen

Schema: 

{
  "detail-type": "LeaseFrozen",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "triggeredBudgetThreshold": 0.95,
      "budget": 100.00,
      "totalSpend": 95.00
    }
  }
}

LeaseUnfrozen

Published when a previously frozen lease is unfrozen and access is restored.

Detail Type: LeaseUnfrozen

Schema: 

{
  "detail-type": "LeaseUnfrozen",
  "detail": {
    "leaseId": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "accountId": "123456789012",
    "maxBudget": 100.00,
    "leaseDurationInHours": 168,
    "reason": "Budget threshold resolved, access restored"
  }
}

Lease assignment events

These events support the lease sharing feature. The solution records the desired set of users and groups for a lease, then processes IAM Identity Center access grants and removals asynchronously through an AWS Step Functions workflow. For more information on the sharing feature, refer to Sharing a lease with additional users and groups in the Manager Guide.

The solution publishes AssignmentCreated and AssignmentRemoved events only for confirmed access changes. A principal that was already assigned and remains assigned produces no event, so the number of these events for a given request does not necessarily match the number of principals on the lease.

AssignmentRequested

Published when the desired assignments for a lease change (for example, when a user is added or removed, or during lease publish, freeze, unfreeze, or termination). This event triggers the assignment processing AWS Step Functions workflow.

Detail Type: AssignmentRequested

Schema: 

{
  "detail-type": "AssignmentRequested",
  "detail": {
    "intent": "UPDATE",
    "leaseId": "550e8400-e29b-41d4-a716-446655440000",
    "requestedBy": "manager@example.com",
    "lockOwnerId": "update-550e8400-e29b-41d4-a716-446655440000",
    "leaseOwnerEmail": "developer@example.com"
  }
}

Intent values: UPDATE, PUBLISH, FREEZE, UNFREEZE, TERMINATE

The lockOwnerId is a lock ownership token, formatted as the lowercased intent followed by a UUID. The solution generates this token when it acquires the lease’s resource lock, and the assignment processing AWS Step Functions workflow uses it to verify it still owns that lock before releasing it.

AssignmentCreated

Published when a principal (user or group) is successfully granted access to a sandbox account. This event triggers an email notification to the lease owner and, for user assignments, to the added user.

Detail Type: AssignmentCreated

Schema: 

{
  "detail-type": "AssignmentCreated",
  "detail": {
    "leaseId": "550e8400-e29b-41d4-a716-446655440000",
    "principalId": "94482488-3041-7098-1234-abcdef123456",
    "principalType": "USER",
    "assigneeEmail": "teammate@example.com",
    "accountId": "123456789012",
    "addedBy": "developer@example.com",
    "leaseOwner": "developer@example.com"
  }
}

Note: assigneeEmail is present for USER assignments and absent for GROUP assignments.

AssignmentRemoved

Published when a principal’s access to a sandbox account is successfully removed (for example, when a user is removed from the assignments, or during lease freeze or termination). This event triggers an email notification to the lease owner.

Detail Type: AssignmentRemoved

Schema: 

{
  "detail-type": "AssignmentRemoved",
  "detail": {
    "leaseId": "550e8400-e29b-41d4-a716-446655440000",
    "principalId": "94482488-3041-7098-1234-abcdef123456",
    "principalType": "USER",
    "assigneeEmail": "teammate@example.com",
    "accountId": "123456789012",
    "removedBy": "developer@example.com",
    "leaseOwner": "developer@example.com"
  }
}

Note: assigneeEmail is present for USER assignments and absent for GROUP assignments.

Account management events

CleanAccountRequest

Published when an account cleanup process is initiated.

Detail Type: CleanAccountRequest

Schema: 

{
  "detail-type": "CleanAccountRequest",
  "detail": {
    "accountId": "123456789012",
    "reason": "Lease terminated - budget exceeded"
  }
}

AccountCleanupSucceeded

Published when an account cleanup process completes successfully.

Detail Type: AccountCleanupSucceeded

Schema: 

{
  "detail-type": "AccountCleanupSucceeded",
  "detail": {
    "accountId": "123456789012",
    "reason": "LEASE_TERMINATION",
    "cleanupExecutionContext": {
      "executionArn": "arn:aws:lambda:us-east-1:123456789012:function:isb-durable-cleanup:live:execution-id",
      "executionStartTime": "2024-01-15T14:30:25Z"
    }
  }
}

AccountCleanupFailed

Published when an account cleanup process fails.

Detail Type: AccountCleanupFailed

Schema: 

{
  "detail-type": "AccountCleanupFailed",
  "detail": {
    "accountId": "123456789012",
    "reason": "LEASE_TERMINATION",
    "cleanupExecutionContext": {
      "executionArn": "arn:aws:lambda:us-east-1:123456789012:function:isb-durable-cleanup:live:execution-id",
      "executionStartTime": "2024-01-15T14:30:25Z"
    }
  }
}

AccountQuarantined

Published when an account is quarantined because of cleanup failures, detected drift, or manual quarantine by an administrator.

Detail Type: AccountQuarantined

Schema: 

{
  "detail-type": "AccountQuarantined",
  "detail": {
    "awsAccountId": "123456789012",
    "reason": "Account cleanup failed after multiple attempts"
  }
}

AccountDriftDetected

Published when an account is detected to be in an unexpected organizational unit.

Detail Type: AccountDriftDetected

Schema: 

{
  "detail-type": "AccountDriftDetected",
  "detail": {
    "accountId": "123456789012",
    "actualOu": "ou-root-1234567890",
    "expectedOu": "ou-sandbox-0987654321"
  }
}

Cost reporting events

GroupCostReportGenerated

Published when a cost report is successfully generated for a group of accounts.

Detail Type: GroupCostReportGenerated

Schema: 

{
  "detail-type": "GroupCostReportGenerated",
  "detail": {
    "reportMonth": "2024-01",
    "fileName": "cost-report-2024-01.csv",
    "bucketName": "innovation-sandbox-reports-bucket",
    "timestamp": "2024-02-01T09:00:00Z"
  }
}

GroupCostReportGeneratedFailure

Published when cost report generation fails.

Detail Type: GroupCostReportGeneratedFailure

Schema: 

{
  "detail-type": "GroupCostReportGeneratedFailure",
  "detail": {
    "reportMonth": "2024-01",
    "timestamp": "2024-02-01T09:00:00Z"
  }
}

Blueprint deployment events

BlueprintDeploymentRequest

Published when a lease with an attached blueprint is approved, triggering the blueprint deployment workflow.

Detail Type: BlueprintDeploymentRequest

Schema: 

{
  "detail-type": "BlueprintDeploymentRequest",
  "detail": {
    "blueprintId": "550e8400-e29b-41d4-a716-446655440000",
    "blueprintName": "Development Environment",
    "leaseId": "650e8400-e29b-41d4-a716-446655440000",
    "userEmail": "developer@example.com",
    "accountId": "123456789012",
    "stackSetId": "arn:aws:cloudformation:us-east-1:123456789012:stackset/dev-env-stackset:abc123",
    "regions": ["us-east-1", "us-west-2"],
    "regionConcurrencyType": "SEQUENTIAL",
    "deploymentTimeoutMinutes": 30,
    "maxConcurrentPercentage": 100,
    "failureTolerancePercentage": 0,
    "concurrencyMode": "STRICT_FAILURE_TOLERANCE"
  }
}

Note: maxConcurrentPercentage, failureTolerancePercentage, and concurrencyMode are optional fields.

BlueprintDeploymentSucceeded

Published when a blueprint deployment completes successfully and the user can access the account with pre-configured resources.

Detail Type: BlueprintDeploymentSucceeded

Schema: 

{
  "detail-type": "BlueprintDeploymentSucceeded",
  "detail": {
    "leaseId": {
      "uuid": "650e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "blueprintId": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": "123456789012",
    "operationId": "abc123-def456-ghi789",
    "duration": 15
  }
}

BlueprintDeploymentFailed

Published when a blueprint deployment fails due to validation errors, deployment failures, or timeouts. The lease transitions to ProvisioningFailed status and the account is sent to cleanup.

Detail Type: BlueprintDeploymentFailed

Schema: 

{
  "detail-type": "BlueprintDeploymentFailed",
  "detail": {
    "leaseId": {
      "uuid": "650e8400-e29b-41d4-a716-446655440000",
      "userEmail": "developer@example.com"
    },
    "blueprintId": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": "123456789012",
    "operationId": "abc123-def456-ghi789",
    "errorType": "DEPLOYMENT_TIMEOUT",
    "errorMessage": "StackSet deployment failed: Resource creation timeout"
  }
}

Note: operationId is optional and may not be present for validation failures that occur before deployment starts.

Common failure reasons:

  • StackSet validation failures (not found, wrong permission model, inactive status)

  • CloudFormation deployment errors (resource creation failures, insufficient permissions)

  • Deployment timeout exceeded (default: 30 minutes, configurable per blueprint)

  • Lambda function errors (crashes, timeouts, throttling)

Schema evolution

Event schemas may evolve over time. Design your integration to be resilient:

  • Ignore unknown fields in event payloads

  • Provide default values for missing optional fields

  • Version your event processing logic when breaking changes occur

For the complete source code, refer to the Innovation Sandbox on AWS GitHub repository.