# Create an integration with an event source outside of AWS
**Note**
AWS CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see [CloudTrail Lake availability change](cloudtrail-lake-service-availability-change.md).
You can use CloudTrail to log and store user activity data from any source in your hybrid environments, such as in-house or SaaS applications hosted on-premises or in the cloud, virtual machines, or containers. You can store, access, analyze, troubleshoot and take action on this data without maintaining multiple log aggregators and reporting tools.
Activity events from non-AWS sources work by using *channels* to bring events into CloudTrail Lake from external partners that work with CloudTrail, or from your own sources. When you create a channel, you choose one or more event data stores to store events that arrive from the channel source. You can change the destination event data stores for a channel as needed, as long as the destination event data stores are set to log `eventCategory="ActivityAuditLog"` events. When you create a channel for events from an external partner, you provide a channel ARN to the partner or source application. The resource policy attached to the channel allows the source to transmit events through the channel. If a channel does not have a resource policy, only the channel owner can call the `PutAuditEvents` API on the channel.
CloudTrail has partnered with many event source providers, such as Okta and LaunchDarkly. When you create an integration with an event source outside AWS, you can choose one of these partners as your event source, or choose **My custom integration** to integrate events from your own sources into CloudTrail. A maximum of one channel is allowed per source.
There are two types of integrations: direct and solution. With direct integrations, the partner calls the `PutAuditEvents` API to deliver events to the event data store for your AWS account. With solution integrations, the application runs in your AWS account and the application calls the `PutAuditEvents` API to deliver events to the event data store for your AWS account.
From the **Integrations** page, you can choose the **Available sources** tab to the view the **Integration type** for partners.
![\[Partner integration type\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/partner-integration-type.png)
To get started, create an integration to log events from partner or other application sources using the CloudTrail console.
**Topics**
+ [Create an integration with a CloudTrail partner with the console](query-event-data-store-integration-partner.md)
+ [Create a custom integration with the console](query-event-data-store-integration-custom.md)
+ [Create, update, and manage CloudTrail Lake integrations with the AWS CLI](lake-integrations-cli.md)
+ [Additional information about integration partners](#cloudtrail-lake-partner-information)
+ [CloudTrail Lake integrations event schema](query-integration-event-schema.md)
# Create an integration with a CloudTrail partner with the console
When you create an integration with an event source outside AWS, you can choose one of these partners as your event source. When you create an integration in CloudTrail with a partner application, the partner needs the Amazon Resource Name (ARN) of the channel that you create in this workflow to send events to CloudTrail. After you create the integration, you finish configuring the integration by following the partner's instructions to provide the required channel ARN to the partner. The integration starts ingesting partner events into CloudTrail after the partner calls `PutAuditEvents` on the integration's channel.
1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. From the navigation pane, under **Lake**, choose **Integrations**.
1. On the **Add integration** page, enter a name for your channel. The name can be 3-128 characters. Only letters, numbers, periods, underscores, and dashes are allowed.
1. Choose the partner application source from which you want to get events. If you're integrating with events from your own applications hosted on-premises or in the cloud, choose **My custom integration**.
1. From **Event delivery location**, choose to log the same activity events to existing event data stores, or create a new event data store.
If you choose to create a new event data store, enter a name for the event data store, choose the pricing option, and specify the retention period in days. The event data store retains event data for the specified number of days.
If you choose to log activity events to one or more existing event data stores, choose the event data stores from the list. The event data stores can only include activity events. The event type in the console must be **Events from integrations**. In the API, the `eventCategory` value must be `ActivityAuditLog`.
1. In **Resource policy**, configure the resource policy for the integration's channel. Resource policies are JSON policy documents that specify what actions a specified principal can perform on the resource and under what conditions. The accounts defined as principals in the resource policy can call the `PutAuditEvents` API to deliver events to your channel. The resource owner has implicit access to the resource if their IAM policy allows the `cloudtrail-data:PutAuditEvents` action.
The information required for the policy is determined by the integration type. For a direction integration, CloudTrail automatically adds the partner's AWS account IDs, and requires you to enter the unique external ID provided by the partner. For a solution integration, you must specify at least one AWS account ID as principal, and can optionally enter an external ID to prevent against confused deputy.
**Note**
If you do not create a resource policy for the channel, only the channel owner can call the `PutAuditEvents` API on the channel.
1. For a direct integration, enter the external ID provided by your partner. The integration partner provides a unique external ID, such as an account ID or a randomly generated string, to use for the integration to prevent against confused deputy. The partner is responsible for creating and providing a unique external ID.
You can choose **How to find this?** to view the partner's documentation that describes how to find the external ID.
![\[Partner documentation for external ID\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/images/integration-external-id.png)
**Note**
If the resource policy includes an external ID, all calls to the `PutAuditEvents` API must include the external ID. However, if the policy does not define an external ID, the partner can still call the `PutAuditEvents` API and specify an `externalId` parameter.
1. For a solution integration, choose **Add AWS account** to specify an AWS account ID to add as a principal in the policy.
1. (Optional) In the **Tags** area, you can add up to 50 tag key and value pairs to help you identify, sort, and control access to your event data store and channel. For more information about how to use IAM policies to authorize access to an event data store based on tags, see [Examples: Denying access to create or delete event data stores based on tags](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-eds-tags). For more information about how you can use tags in AWS, see [Tagging AWS resources](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html) in the *AWS General Reference*.
1. When you are ready to create the new integration, choose **Add integration**. There is no review page. CloudTrail creates the integration, but you must provide the channel Amazon Resource Name (ARN) to the partner application. Instructions for providing the channel ARN to the partner application are found on the partner documentation website. For more information, choose the **Learn more** link for the partner on the **Available sources** tab of the **Integrations** page to open the partner's page in AWS Marketplace.
To finish the setup for your integration, provide the channel ARN to the partner or source application. Depending upon the integration type, either you, the partner, or the application runs the `PutAuditEvents` API to deliver activity events to the event data store for your AWS account. After your activity events are delivered, you can use CloudTrail Lake to search, query, and analyze the data that is logged from your applications. Your event data includes fields that match CloudTrail event payload, such as `eventVersion`, `eventSource`, and `userIdentity`.
# Create a custom integration with the console
You can use CloudTrail to log and store user activity data from any source in your hybrid environments, such as in-house or SaaS applications hosted on-premises or in the cloud, virtual machines, or containers. Perform the first half of this procedure in the CloudTrail Lake console, then call the [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API to ingest events, providing your channel ARN and event payload. After you use the `PutAuditEvents` API to ingest your application activity into CloudTrail, you can use CloudTrail Lake to search, query, and analyze the data that is logged from your applications.
1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. From the navigation pane, under **Lake**, choose **Integrations**.
1. On the **Add integration** page, enter a name for your channel. The name can be 3-128 characters. Only letters, numbers, periods, underscores, and dashes are allowed.
1. Choose **My custom integration**.
1. From **Event delivery location**, choose to log the same activity events to existing event data stores, or create a new event data store.
If you choose to create a new event data store, enter a name for the event data store and specify the retention period in days. You can keep the event data in an event data store for up to 3,653 days (about 10 years) if you choose the **One-year extendable retention pricing** option, or up to 2,557 days (about 7 years) if you choose the **Seven-year retention pricing** option.
If you choose to log activity events to one or more existing event data stores, choose the event data stores from the list. The event data stores can only include activity events. The event type in the console must be **Events from integrations**. In the API, the `eventCategory` value must be `ActivityAuditLog`.
1. In **Resource policy**, configure the resource policy for the integration's channel. Resource policies are JSON policy documents that specify what actions a specified principal can perform on the resource and under what conditions. The accounts defined as principals in the resource policy can call the `PutAuditEvents` API to deliver events to your channel.
**Note**
If you do not create a resource policy for the channel, only the channel owner can call the `PutAuditEvents` API on the channel.
1. (Optional) Enter a unique external ID to provide an extra layer of protection. The external ID is a unique string such as an account ID or a randomly generated string, to prevent against confused deputy.
**Note**
If the resource policy includes an external ID, all calls to the `PutAuditEvents` API must include the external ID. However, if the policy does not define an external ID, you can still call the `PutAuditEvents` API and specify an `externalId` parameter.
1. Choose **Add AWS account** to specify each AWS account ID to add as a principal in the resource policy for the channel.
1. (Optional) In the **Tags** area, you can add up to 50 tag key and value pairs to help you identify, sort, and control access to your event data store and channel. For more information about how to use IAM policies to authorize access to an event data store based on tags, see [Examples: Denying access to create or delete event data stores based on tags](security_iam_id-based-policy-examples.md#security_iam_id-based-policy-examples-eds-tags). For more information about how you can use tags in AWS, see [Tagging your AWS resources](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html) in the *AWS General Reference*.
1. When you are ready to create the new integration, choose **Add integration**. There is no review page. CloudTrail creates the integration, but to integrate your custom events, you must specify the channel ARN in a [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) request.
1. Call the `PutAuditEvents` API to ingest your activity events into CloudTrail. You can add up to 100 activity events (or up to 1 MB) per `PutAuditEvents` request. You'll need the channel ARN that you created in preceding steps, the payload of events that you want CloudTrail to add, and the external ID (if specified for your resource policy). Be sure that there is no sensitive or personally-identifying information in event payload before ingesting it into CloudTrail. Events that you ingest into CloudTrail must follow the [CloudTrail Lake integrations event schema](query-integration-event-schema.md).
**Tip**
Use [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) to be sure you are running the most current AWS APIs.
The following examples show how to use the **put-audit-events** CLI command. The **--audit-events** and **--channel-arn** parameters are required. You need the ARN of the channel that you created in the preceding steps, which you can copy from the integration details page. The value of **--audit-events** is a JSON array of event objects. `--audit-events` includes a required ID from the event, the required payload of the event as the value of `EventData`, and an [optional checksum](#event-data-store-integration-custom-checksum) to help validate the integrity of the event after ingestion into CloudTrail.
```
aws cloudtrail-data put-audit-events \
--region region \
--channel-arn $ChannelArn \
--audit-events \
id="event_ID",eventData='"{event_payload}"' \
id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"
```
The following is an example command with two event examples.
```
aws cloudtrail-data put-audit-events \
--region us-east-1 \
--channel-arn arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--audit-events \
id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ...
\}"' \
id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ...
\}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"
```
The following example command adds the `--cli-input-json` parameter to specify a JSON file (`custom-events.json`) of event payload.
```
aws cloudtrail-data put-audit-events \
--channel-arn $channelArn \
--cli-input-json file://custom-events.json \
--region us-east-1
```
The following are the sample contents of the example JSON file, `custom-events.json`.
```
{
"auditEvents": [
{
"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
\"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
\"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
\"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
\"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
\"additionalEventData\":{\"key\":\"value\"},
\"sourceIPAddress\":\"source_IP_address\",\"recipientAccountId\":\"recipient_account_ID\"}",
"id": "1"
}
]
}
```
## (Optional) Calculate a checksum value
The checksum that you specify as the value of `EventDataChecksum` in a `PutAuditEvents` request helps you verify that CloudTrail receives the event that matches with the checksum; it helps verify the integrity of events. The checksum value is a base64-SHA256 algorithm that you calculate by running the following command.
```
printf %s "{"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
\"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
\"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
\"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
\"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
\"additionalEventData\":{\"key\":\"value\"},
\"sourceIPAddress\":\"source_IP_address\",
\"recipientAccountId\":\"recipient_account_ID\"}",
"id": "1"}" \
| openssl dgst -binary -sha256 | base64
```
The command returns the checksum. The following is an example.
```
EXAMPLEHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=
```
The checksum value becomes the value of `EventDataChecksum` in your `PutAuditEvents` request. If the checksum doesn't match with the one for the provided event, CloudTrail rejects the event with an `InvalidChecksum` error.
# Create, update, and manage CloudTrail Lake integrations with the AWS CLI
This section describes the commands you can use to create, update and manage your CloudTrail Lake integrations using the AWS CLI.
When using the AWS CLI, remember that your commands run in the AWS Region configured for your profile. If you want to run the commands in a different Region, either change the default Region for your profile, or use the **--region** parameter with the command.
## Available commands for CloudTrail Lake integrations
Commands for creating, updating, and managing integrations in CloudTrail Lake include:
+ `create-event-data-store` to create an event data store for events outside of AWS.
+ `delete-channel` to delete a channel used for an integration.
+ `[delete-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/delete-resource-policy.html)` to delete the resource policy attached to a channel for a CloudTrail Lake integration.
+ `[get-channel](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-channel.html)` to return information about a CloudTrail channel.
+ `[get-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/get-resource-policy.html)` to retrieve the JSON text of the resource-based policy document attached to the CloudTrail channel.
+ `[list-channels](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/list-channels.html)` to list the channels in the current account, and their source names.
+ `[put-audit-events](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail-data/put-audit-events.html)` to ingest your application events into CloudTrail Lake. A required parameter, `auditEvents`, accepts the JSON records (also called payload) of events that you want CloudTrail to ingest. You can add up to 100 of these events (or up to 1 MB) per `PutAuditEvents` request.
+ `[put-resource-policy](https://docs.aws.amazon.com/cli/latest/reference/cloudtrail/put-resource-policy.html)` to attach a resource-based permission policy to a CloudTrail channel that is used for an integration with an event source outside of AWS. For more information about resource-based policies, see [AWS CloudTrail resource-based policy examples](security_iam_resource-based-policy-examples.md).
+ `update-channel` to update a channel specified by a required channel ARN or UUID.
For a list of available commands for CloudTrail Lake event data stores, see [Available commands for event data stores](lake-eds-cli.md#lake-eds-cli-commands).
For a list of available commands for CloudTrail Lake queries, see [Available commands for CloudTrail Lake queries](lake-queries-cli.md#lake-queries-cli-commands).
For a list of available commands for CloudTrail Lake dashboards, see [Available commands for dashboards](lake-dashboard-cli.md#lake-dashboard-cli-commands).
# Create an integration to log events from outside AWS with the AWS CLI
This section describes how you can use the AWS CLI to create a CloudTrail Lake integration to log events from outside of AWS.
In the AWS CLI, you create an integration in four commands (three if you already have an event data store that meets the criteria). Event data stores that you use as the destinations for an integration must be for a single Region and single account; they cannot be multi-region, they cannot log events for organizations in AWS Organizations, and they can only include activity events. The event type in the console must be **Events from integrations**. In the API, the `eventCategory` value must be `ActivityAuditLog`. For more information about integrations, see [Create an integration with an event source outside of AWS](query-event-data-store-integration.md).
1. Run [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/index.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/index.html) to create an event data store, if you do not already have one or more event data stores that you can use for the integration.
The following example AWS CLI command creates an event data store that logs events from outside AWS. For activity events, the `eventCategory` field selector value is `ActivityAuditLog`. The event data store has a retention period of 90 days set. By default, the event data store collects events from all Regions, but because this is collecting non-AWS events, set it to a single Region by adding the `--no-multi-region-enabled` option. Termination protection is enabled by default, and the event data store does not collect events for accounts in an organization.
```
aws cloudtrail create-event-data-store \
--name my-event-data-store \
--no-multi-region-enabled \
--retention-period 90 \
--advanced-event-selectors '[
{
"Name": "Select all external events",
"FieldSelectors": [
{ "Field": "eventCategory", "Equals": ["ActivityAuditLog"] }
]
}
]'
```
The following is an example response.
```
{
"EventDataStoreArn": "arn:aws:cloudtrail:us-east-1:123456789012:eventdatastore/EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE",
"Name": "my-event-data-store",
"AdvancedEventSelectors": [
{
"Name": "Select all external events",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"ActivityAuditLog"
]
}
]
}
],
"MultiRegionEnabled": true,
"OrganizationEnabled": false,
"BillingMode": "EXTENDABLE_RETENTION_PRICING",
"RetentionPeriod": 90,
"TerminationProtectionEnabled": true,
"CreatedTimestamp": "2023-10-27T10:55:55.384000-04:00",
"UpdatedTimestamp": "2023-10-27T10:57:05.549000-04:00"
}
```
You'll need the event data store ID (the suffix of the ARN, or `EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE` in the preceding response example) to go on to the next step and create your channel.
1. Run the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-channel.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/create-channel.html) command to create a channel that allows a partner or source application to send events to an event data store in CloudTrail.
A channel has the following components:
**Source**
CloudTrail uses this information to determine the partners that are sending event data to CloudTrail on your behalf. A source is required, and can be either `Custom` for all valid non-AWS events, or the name of a partner event source. A maximum of one channel is allowed per source.
For information about the `Source` values for available partners, see [Additional information about integration partners](query-event-data-store-integration.md#cloudtrail-lake-partner-information).
**Ingestion status**
The channel status shows when the last events were received from a channel source.
**Destinations**
The destinations are the CloudTrail Lake event data stores that are receiving events from the channel. You can change destination event data stores for a channel.
To stop receiving events from a source, delete the channel.
You need the ID of at least one destination event data store to run this command. The valid type of destination is `EVENT_DATA_STORE`. You can send ingested events to more than one event data store. The following example command creates a channel that sends events to two event data stores, represented by their IDs in the `Location` attribute of the `--destinations` parameter. The `--destinations`, `--name`, and `--source` parameters are required. To ingest events from a CloudTrail partner, specify the name of the partner as the value of `--source`. To ingest events from your own applications outside AWS, specify `Custom` as the value of `--source`.
```
aws cloudtrail create-channel \
--region us-east-1 \
--destinations '[{"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE"}, {"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEg922-5n2l-3vz1- apqw8EXAMPLE"}]'
--name my-partner-channel \
--source $partnerSourceName \
```
In the response to your **create-channel** command, copy the ARN of the new channel. You need the ARN to run the `put-resource-policy` and `put-audit-events` commands in the next steps.
1. Run the **put-resource-policy** command to attach a resource policy to the channel. Resource policies are JSON policy documents that specify what actions a specified principal can perform on the resource and under what conditions. The accounts defined as principals in the channel's resource policy can call the `PutAuditEvents` API to deliver events.
**Note**
If you do not create a resource policy for the channel, only the channel owner can call the `PutAuditEvents` API on the channel.
The information required for the policy is determined by the integration type.
+ For a direction integration, CloudTrail requires the policy to contain the partner's AWS account IDs, and requires you to enter the unique external ID provided by the partner. CloudTrail automatically adds the partner's AWS account IDs to the resource policy when you create an integration using the CloudTrail console. Refer to the [partner's documentation](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-event-data-store-integration.html#cloudtrail-lake-partner-information#lake-integration-partner-documentation) to learn how to get the AWS account numbers required for the policy.
+ For a solution integration, you must specify at least one AWS account ID as principal, and can optionally enter an external ID to prevent against confused deputy.
The following are requirements for the resource policy:
+ The resource ARN defined in the policy must match the channel ARN the policy is attached to.
+ The policy contains only one action: cloudtrail-data:PutAuditEvents
+ The policy contains at least one statement. The policy can have a maximum of 20 statements.
+ Each statement contains at least one principal. A statement can have a maximum of 50 principals.
```
aws cloudtrail put-resource-policy \
--resource-arn "channelARN" \
--policy "{
"Version": "2012-10-17",
"Statement":
[
{
"Sid": "ChannelPolicy",
"Effect": "Allow",
"Principal":
{
"AWS":
[
"arn:aws:iam::111122223333:root",
"arn:aws:iam::444455556666:root",
"arn:aws:iam::123456789012:root"
]
},
"Action": "cloudtrail-data:PutAuditEvents",
"Resource": "arn:aws:cloudtrail:us-east-1:777788889999:channel/EXAMPLE-80b5-40a7-ae65-6e099392355b",
"Condition":
{
"StringEquals":
{
"cloudtrail:ExternalId": "UniqueExternalIDFromPartner"
}
}
}
]
}"
```
For more information about resource policies, see [AWS CloudTrail resource-based policy examples](security_iam_resource-based-policy-examples.md).
1. Run the [https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html](https://docs.aws.amazon.com/awscloudtraildata/latest/APIReference/API_PutAuditEvents.html) API to ingest your activity events into CloudTrail. You'll need the payload of events that you want CloudTrail to add. Be sure that there is no sensitive or personally-identifying information in event payload before ingesting it into CloudTrail. Note that the `PutAuditEvents` API uses the `cloudtrail-data` CLI endpoint, not the `cloudtrail` endpoint.
The following examples show how to use the **put-audit-events** CLI command. The **--audit-events** and **--channel-arn** parameters are required. The **--external-id** parameter is required if an external ID is defined in the resource policy. You need the ARN of the channel that you created in the preceding step. The value of **--audit-events** is a JSON array of event objects. `--audit-events` includes a required ID from the event, the required payload of the event as the value of `EventData`, and an [optional checksum](#lake-cli-integration-checksum.title) to help validate the integrity of the event after ingestion into CloudTrail.
```
aws cloudtrail-data put-audit-events \
--channel-arn $ChannelArn \
--external-id $UniqueExternalIDFromPartner \
--audit-events \
id="event_ID",eventData='"{event_payload}"' \
id="event_ID",eventData='"{event_payload}"',eventDataChecksum="optional_checksum"
```
The following is an example command with two event examples.
```
aws cloudtrail-data put-audit-events \
--channel-arn arn:aws:cloudtrail:us-east-1:123456789012:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--external-id UniqueExternalIDFromPartner \
--audit-events \
id="EXAMPLE3-0f1f-4a85-9664-d50a3EXAMPLE",eventData='"{\"eventVersion\":\0.01\",\"eventSource\":\"custom1.domain.com\", ...
\}"' \
id="EXAMPLE7-a999-486d-b241-b33a1EXAMPLE",eventData='"{\"eventVersion\":\0.02\",\"eventSource\":\"custom2.domain.com\", ...
\}"',eventDataChecksum="EXAMPLE6e7dd61f3ead...93a691d8EXAMPLE"
```
The following example command adds the `--cli-input-json` parameter to specify a JSON file (`custom-events.json`) of event payload.
```
aws cloudtrail-data put-audit-events --channel-arn $channelArn --external-id $UniqueExternalIDFromPartner --cli-input-json file://custom-events.json --region us-east-1
```
The following are the sample contents of the example JSON file, `custom-events.json`.
```
{
"auditEvents": [
{
"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
\"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
\"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
\"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
\"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
\"additionalEventData\":{\"key\":\"value\"},
\"sourceIPAddress\":\"12.34.56.78\",\"recipientAccountId\":\"152089810396\"}",
"id": "1"
}
]
}
```
You can verify that the integration is working, and CloudTrail is ingesting events from the source correctly, by running the [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/get-channel.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/cloudtrail/get-channel.html) command. The output of **get-channel** shows the most recent time stamp that CloudTrail received events.
```
aws cloudtrail get-channel --channel arn:aws:cloudtrail:us-east-1:01234567890:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE
```
## (Optional) Calculate a checksum value
The checksum that you specify as the value of `EventDataChecksum` in a `PutAuditEvents` request helps you verify that CloudTrail receives the event that matches with the checksum; it helps verify the integrity of events. The checksum value is a base64-SHA256 algorithm that you calculate by running the following command.
```
printf %s "{"eventData": "{\"version\":\"eventData.version\",\"UID\":\"UID\",
\"userIdentity\":{\"type\":\"CustomUserIdentity\",\"principalId\":\"principalId\",
\"details\":{\"key\":\"value\"}},\"eventTime\":\"2021-10-27T12:13:14Z\",\"eventName\":\"eventName\",
\"userAgent\":\"userAgent\",\"eventSource\":\"eventSource\",
\"requestParameters\":{\"key\":\"value\"},\"responseElements\":{\"key\":\"value\"},
\"additionalEventData\":{\"key\":\"value\"},
\"sourceIPAddress\":\"source_IP_address\",
\"recipientAccountId\":\"recipient_account_ID\"}",
"id": "1"}" \
| openssl dgst -binary -sha256 | base64
```
The command returns the checksum. The following is an example.
```
EXAMPLEDHjkI8iehvCUCWTIAbNYkOgO/t0YNw+7rrQE=
```
The checksum value becomes the value of `EventDataChecksum` in your `PutAuditEvents` request. If the checksum doesn't match with the one for the provided event, CloudTrail rejects the event with an `InvalidChecksum` error.
# Update a channel with the AWS CLI
This section describes how you can use the AWS CLI to update a channel for a CloudTrail Lake integration. You can run the `update-channel` command to update the name of the channel or to specify a different destination event data store. You cannot update the source of a channel.
When you run the command, the `--channel` parameter is required.
The following is an example that demonstrates how to update the channel name and destination.
```
aws cloudtrail update-channel \
--channel aws:cloudtrail:us-east-1:123456789012:channel/EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE \
--name "new-channel-name" \
--destinations '[{"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEf852-4e8f-8bd1-bcf6cEXAMPLE"}, {"Type": "EVENT_DATA_STORE", "Location": "EXAMPLEg922-5n2l-3vz1- apqw8EXAMPLE"}]'
```
# Delete a channel to delete an integration with the AWS CLI
This section describes how to run the `delete-channel` command to delete the channel for a CloudTrail Lake integration. You would delete a channel, if you wanted to stop ingesting partner or other activity events outside of AWS. The ARN or channel ID (the ARN suffix) of the channel that you want to delete is required.
The following example shows how to delete the channel.
```
aws cloudtrail delete-channel \
--channel EXAMPLE8-0558-4f7e-a06a-43969EXAMPLE
```
## Additional information about integration partners
The table in this section provides the source name for each integration partner and identifies the integration type (direct or solution).
The information in the **Source name** column is required when calling the `CreateChannel` API. You specify the source name as the value for the `Source` parameter.
****
| Partner name (console) | Source name (API) | Integration type |
| --- | --- | --- |
| My custom integration | Custom | solution |
| Cloud Storage Security | CloudStorageSecurityConsole | solution |
| Clumio | Clumio | direct |
| CrowdStrike | CrowdStrike | solution |
| CyberArk | CyberArk | solution |
| GitHub | GitHub | solution |
| Kong Inc | KongGatewayEnterprise | solution |
| LaunchDarkly | LaunchDarkly | direct |
| Netskope | NetskopeCloudExchange | solution |
| Nordcloud, an IBM Company | IBMMulticloud | direct |
| MontyCloud | MontyCloud | direct |
| Okta | OktaSystemLogEvents | solution |
| One Identity | OneLogin | solution |
| Shoreline.io | Shoreline | solution |
| Snyk.io | Snyk | direct |
| Wiz | WizAuditLogs | solution |
### View partner documentation
You can learn more about a partner's integration with CloudTrail Lake by viewing their documentation.
**To view partner documentation**
1. Sign in to the AWS Management Console and open the CloudTrail console at [https://console.aws.amazon.com/cloudtrail/](https://console.aws.amazon.com/cloudtrail/).
1. From the navigation pane, under **Lake**, choose **Integrations**.
1. From the **Integrations** page, choose **Available sources**, then choose **Learn more** for the partner whose documentation you want to view.
# CloudTrail Lake integrations event schema
The following table describes the required and optional schema elements that match those in CloudTrail event records. The contents of `eventData` are provided by your events; other fields are provided by CloudTrail after ingestion.
CloudTrail event record contents are described in more detail in [CloudTrail record contents for management, data, and network activity events](cloudtrail-event-reference-record-contents.md).
+ [Fields that are provided by CloudTrail after ingestion](#fields-cloudtrail)
+ [Fields that are provided by your events](#fields-event)
The following fields are provided by CloudTrail after ingestion:
| Field name | Input type | Requirement | Description |
| --- | --- | --- | --- |
| eventVersion | string | Required | The event version. |
| eventCategory | string | Required | The event category. For non-AWS events, the value is `ActivityAuditLog`. |
| eventType | string | Required | The event type. For non-AWS events, the valid value is `ActivityLog`. |
| eventID | string | Required | A unique ID for an event. |
| eventTime | string | Required | Event timestamp, in `yyyy-MM-DDTHH:mm:ss` format, in Universal Coordinated Time (UTC). |
| awsRegion | string | Required | The AWS Region where the `PutAuditEvents` call was made. |
| recipientAccountId | string | Required | Represents the account ID that received this event. CloudTrail populates this field by calculating it from event payload. |
| addendum | - | Optional | Shows information about why event processing was delayed. If information was missing from an existing event, the addendum block includes the missing information and a reason for why it was missing. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The reason that the event or some of its contents were missing. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The event record fields that are updated by the addendum. This is only provided if the reason is `UPDATED_DATA`. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The original event UID from the source. This is only provided if the reason is `UPDATED_DATA`. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The original event ID. This is only provided if the reason is `UPDATED_DATA`. |
| metadata | - | Required | Information about the channel that the event used. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The timestamp when the event was processed, in `yyyy-MM-DDTHH:mm:ss` format, in Universal Coordinated Time (UTC). |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The ARN of the channel that the event used. |
The following fields are provided by customer events:
| Field name | Input type | Requirement | Description |
| --- | --- | --- | --- |
| eventData | - | Required | The audit data sent to CloudTrail in a PutAuditEvents call. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The version of the event from its source. Length constraints: Maximum length of 256. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | - | Required | Information about the user who made a request. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The type of user identity. Length constraints: Maximum length of 128. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | A unique identifier for the actor of the event. Length constraints: Maximum length of 1024. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | JSON object | Optional | Additional information about the identity. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The agent through which the request was made. Length constraints: Maximum length of 1024. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | This is the partner event source, or the custom application about which events are logged. Length constraints: Maximum length of 1024. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The requested action, one of the actions in the API for the source service or application. Length constraints: Maximum length of 1024. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | Event timestamp, in `yyyy-MM-DDTHH:mm:ss` format, in Universal Coordinated Time (UTC). |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | The UID value that identifies the request. The service or application that is called generates this value. Length constraints: Maximum length of 1024. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | JSON object | Optional | The parameters, if any, that were sent with the request. This field has a maximum size of 100 kB, and content exceeding the limit is rejected. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | JSON object | Optional | The response element for actions that make changes (create, update, or delete actions). This field has a maximum size of 100 kB, and content exceeding the limit is rejected. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | A string representing an error for the event. Length constraints: Maximum length of 256. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The description of the error. Length constraints: Maximum length of 256. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Optional | The IP address from which the request was made. Both IPv4 and IPv6 addresses are accepted. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | string | Required | Represents the account ID that received this event. The account ID must be the same as the AWS account ID that owns the channel. |
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/awscloudtrail/latest/userguide/query-integration-event-schema.html) | JSON object | Optional | Additional data about the event that was not part of the request or response. This field has a maximum size of 28 kB, and content exceeding that limit is rejected. |
The following example shows the hierarchy of schema elements that match those in CloudTrail event records.
```
{
"eventVersion": String,
"eventCategory": String,
"eventType": String,
"eventID": String,
"eventTime": String,
"awsRegion": String,
"recipientAccountId": String,
"addendum": {
"reason": String,
"updatedFields": String,
"originalUID": String,
"originalEventID": String
},
"metadata" : {
"ingestionTime": String,
"channelARN": String
},
"eventData": {
"version": String,
"userIdentity": {
"type": String,
"principalId": String,
"details": {
JSON
}
},
"userAgent": String,
"eventSource": String,
"eventName": String,
"eventTime": String,
"UID": String,
"requestParameters": {
JSON
},
"responseElements": {
JSON
},
"errorCode": String,
"errorMessage": String,
"sourceIPAddress": String,
"recipientAccountId": String,
"additionalEventData": {
JSON
}
}
}
```