# Event schemas reference
<a name="event-schemas-reference"></a>

Innovation Sandbox on AWS publishes events to Amazon EventBridge to enable integration with external systems. This section provides a comprehensive reference of all event schemas that customers can use to build integrations with their own systems.

All events are published to the Innovation Sandbox EventBridge custom bus with a consistent structure and follow the AWS EventBridge event pattern.

## Event structure
<a name="event-structure"></a>

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
<a name="event-categories"></a>

Events are organized into the following categories:
+  **Lease Lifecycle Events** - Lease creation, approval, denial, and termination
+  **Lease Monitoring Events** - Budget and duration threshold alerts
+  **Account Management Events** - Account cleanup and drift detection
+  **Cost Reporting Events** - Cost report generation and failures
+  **Blueprint Deployment Events** - Blueprint deployment requests, successes, and failures

## Lease lifecycle events
<a name="lease-lifecycle-events"></a>

### LeaseRequested
<a name="lease-requested"></a>

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@company.com"
    },
    "comments": "Need AWS environment for ML experimentation",
    "userEmail": "developer@company.com",
    "requiresManualApproval": true
  }
}
```

### LeaseApproved
<a name="lease-approved"></a>

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@company.com",
    "userEmail": "developer@company.com"
  }
}
```

### LeaseDenied
<a name="lease-denied"></a>

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@company.com",
    "userEmail": "developer@company.com"
  }
}
```

### LeaseTerminated
<a name="lease-terminated"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "budget": 100.00,
      "totalSpend": 105.50
    }
  }
}
```

 **Reason Types:** `Expired`, `BudgetExceeded`, `ManuallyTerminated`, `AccountQuarantined`, `Ejected` 

## Lease monitoring events
<a name="lease-monitoring-events"></a>

### LeaseBudgetThresholdAlert
<a name="lease-budget-threshold-alert"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "budget": 100.00,
    "totalSpend": 80.00,
    "budgetThresholdTriggered": 0.8,
    "actionRequested": "ALERT"
  }
}
```

### LeaseBudgetExceeded
<a name="lease-budget-exceeded"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "budget": 100.00,
    "totalSpend": 105.50
  }
}
```

### LeaseDurationThresholdAlert
<a name="lease-duration-threshold-alert"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "triggeredDurationThreshold": 24,
    "leaseDurationInHours": 168,
    "actionRequested": "ALERT"
  }
}
```

### LeaseFreezingThresholdAlert
<a name="lease-freezing-threshold-alert"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "triggeredBudgetThreshold": 0.95,
      "budget": 100.00,
      "totalSpend": 95.00
    }
  }
}
```

### LeaseExpired
<a name="lease-expired"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "leaseExpirationDate": "2024-01-22T14:30:25Z"
  }
}
```

### LeaseFrozen
<a name="lease-frozen"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "reason": {
      "type": "BudgetExceeded",
      "triggeredBudgetThreshold": 0.95,
      "budget": 100.00,
      "totalSpend": 95.00
    }
  }
}
```

### LeaseUnfrozen
<a name="lease-unfrozen"></a>

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@company.com"
    },
    "accountId": "123456789012",
    "maxBudget": 100.00,
    "leaseDurationInHours": 168,
    "reason": "Budget threshold resolved, access restored"
  }
}
```

## Account management events
<a name="account-management-events"></a>

### CleanAccountRequest
<a name="clean-account-request"></a>

Published when an account cleanup process is initiated.

 **Detail Type:** `CleanAccountRequest` 

 **Schema:** 

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

### AccountCleanupSucceeded
<a name="account-cleanup-succeeded"></a>

Published when an account cleanup process completes successfully.

 **Detail Type:** `AccountCleanupSucceeded` 

 **Schema:** 

```
{
  "detail-type": "AccountCleanupSucceeded",
  "detail": {
    "accountId": "123456789012",
    "reason": "LEASE_TERMINATION",
    "cleanupExecutionContext": {
      "stateMachineExecutionArn": "arn:aws:states:us-east-1:123456789012:execution:cleanup-state-machine:execution-id",
      "stateMachineExecutionStartTime": "2024-01-15T14:30:25Z"
    }
  }
}
```

### AccountCleanupFailed
<a name="account-cleanup-failed"></a>

Published when an account cleanup process fails.

 **Detail Type:** `AccountCleanupFailed` 

 **Schema:** 

```
{
  "detail-type": "AccountCleanupFailed",
  "detail": {
    "accountId": "123456789012",
    "reason": "LEASE_TERMINATION",
    "cleanupExecutionContext": {
      "stateMachineExecutionArn": "arn:aws:states:us-east-1:123456789012:execution:cleanup-state-machine:execution-id",
      "stateMachineExecutionStartTime": "2024-01-15T14:30:25Z"
    }
  }
}
```

### AccountQuarantined
<a name="account-quarantined"></a>

Published when an account is quarantined due to cleanup failures or other issues.

 **Detail Type:** `AccountQuarantined` 

 **Schema:** 

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

### AccountDriftDetected
<a name="account-drift-detected"></a>

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
<a name="cost-reporting-events"></a>

### GroupCostReportGenerated
<a name="group-cost-report-generated"></a>

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
<a name="group-cost-report-generated-failure"></a>

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
<a name="blueprint-deployment-events"></a>

### BlueprintDeploymentRequest
<a name="blueprint-deployment-request"></a>

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@company.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
<a name="blueprint-deployment-succeeded"></a>

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@company.com"
    },
    "blueprintId": "550e8400-e29b-41d4-a716-446655440000",
    "accountId": "123456789012",
    "operationId": "abc123-def456-ghi789",
    "duration": 15
  }
}
```

### BlueprintDeploymentFailed
<a name="blueprint-deployment-failed"></a>

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@company.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
<a name="schema-evolution"></a>

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](https://github.com/aws-solutions/innovation-sandbox-on-aws).