Using Amazon EventBridge with IVS Real-Time Streaming
You can use Amazon EventBridge to monitor your Amazon Interactive Video Service (IVS) streams.
Amazon IVS sends change events about the status of your streams to Amazon EventBridge. All events that are delivered are valid. However, events are sent on a best-effort basis, which means there is no guarantee that:
-
Events are delivered — A designated event can occur (e.g., a participant published) but it is possible that Amazon IVS will not send a corresponding event to EventBridge. Amazon IVS tries to deliver events for several hours before giving up.
-
Events that are delivered will arrive in a specified timeframe — You may receive events up to a few hours old.
-
Events are delivered in order — Events may be out of order, especially if they are sent within a short time of each other. For example, you could see Participant Unpublished before Participant Published.
While it's rare for events to be missing, late, or out of sequence, you should handle these possibilities if you write business-critical programs that depend on the order or existence of notification events.
You can create EventBridge rules for any of the following events.
| Event Type | Event | Sent When ... |
|---|---|---|
| IVS Composition State Change | Destination Failure | An attempt to output to a Destination failed. For example, broadcasting to a channel failed because there was no stream key or another broadcast was happening. |
| IVS Composition State Change | Destination Start | Output to a Destination successfully started. |
| IVS Composition State Change | Destination End | Output to a Destination finished. |
| IVS Composition State Change | Destination Reconnecting | Output to a Destination was interrupted and a reconnect is being attempted. |
| IVS Composition State Change | Session Start | A Composition session was created. This event fires when a Composition process pipeline successfully initializes. At this point, the Composition pipeline has successfully subscribed to a Stage and is receiving media and able to compose video. |
| IVS Composition State Change | Session End | A Composition session completed. |
| IVS Composition State Change | Session Failure | A Composition pipeline failed to initialize due to Stage resources not being available, or any other internal error. |
| IVS Participant Recording State Change | Recording Start | A publisher has connected to the stage and is being recorded to S3. |
| IVS Participant Recording State Change | Recording End | A publisher has disconnected from the stage and all remaining files have been written to S3. |
| IVS Participant Recording State Change | Recording Start Failure | A publisher connects to the stage, but recording fails to start due to errors (for example, the S3 bucket does not exist or is not in the correct region). This publisher's live stream is not recorded |
| IVS Participant Recording State Change | Recording End Failure | Recording ends with failure, due to errors encountered during recording (e.g., if the attempt to write the media playlist continuously fails). Some objects may still be written to the configured storage location. |
| IVS Stage Update | Participant Published | A participant begins publishing to a stage. |
| IVS Stage Update | Participant Unpublished | A participant has stopped publishing to a stage. |
| IVS Stage Update | Participant Publish Error | A participant's attempt to publish to a stage failed. |
Creating Amazon EventBridge Rules for Amazon IVS
You can create a rule that triggers on an event emitted by Amazon IVS. Follow the steps in Create a rule in Amazon EventBridge in the Amazon EventBridge User Guide. When selecting a service, choose Interactive Video Service (IVS).
Examples: Composition State Change
Destination Failure: This event is sent when an attempt to output to a Destination failed. For example, broadcasting to a channel failed because there was no stream key or another broadcast was happening.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Destination Failure", "stage_arn": "<stage-arn>", "id": "<Destination-id>", "reason": "eg. stream key invalid" } }
Destination Start: This event is sent when output to a Destination successfully started.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Destination Start", "stage_arn": "<stage-arn>", "id": "<destination-id>", } }
Destination End: This event is sent when output to a Destination finished.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Destination End", "stage_arn": "<stage-arn>", "id": "<Destination-id>", } }
Destination Reconnecting: This event is sent when output to a Destination was interrupted and a reconnect is being attempted.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Destination Reconnecting", "stage_arn": "<stage-arn>", "id": "<Destination-id>", } }
Session Start: This event is sent when a Composition session was created. This event fires when a Composition process pipeline successfully initializes. At this point, the Composition pipeline has successfully subscribed to a Stage and is receiving media and able to compose video.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Session Start", "stage_arn": "<stage-arn>" } }
Session End: This event is sent when a Composition session completed and all resources were deleted.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Session End", "stage_arn": "<stage-arn>" } }
Session Failure: This event is sent when a Composition pipeline failed to initialize due to Stage resources not being available, no participants being in the stage, or any other internal error.
{ "version": "0", "id": "01234567-0123-0123-0123-012345678901", "detail-type": "IVS Composition State Change", "source": "aws.ivs", "account": "aws_account_id", "time": "2017-06-12T10:23:43Z", "region": "us-east-1", "resources": [ "arn:aws:ivs:us-east-1:aws_account_id:composition/123456789012" ], "detail": { "event_name": "Session Failure", "stage_arn": "<stage-arn>", "reason": "eg. no participants in the stage" } }
Examples: Individual Participant Recording State Change
Recording Start: This event is sent when a publisher has connected to the stage and is being recorded to S3.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Participant Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2024-03-13T22:09:58Z", "region": "us-east-1", "resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Recording Start", "participant_id": "xYz1c2d3e4f", "recording_s3_bucket_name": "bucket-name", "recording_s3_key_prefix": "<stage_id>/<session_id>/<participant_id>/2024-01-01T12-00-55Z" } }
Recording End: This event is sent when a publisher has disconnected from the stage and all remaining files have been written to S3.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Participant Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2024-03-13T22:19:04Z", "region": "us-east-1", "resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Recording End", "participant_id": "xYz1c2d3e4f", "recording_s3_bucket_name": "bucket-name", "recording_s3_key_prefix": "<stage_id>/<session_id>/<participant_id>/2024-01-01T12-00-55Z" "recording_duration_ms": 547327 } }
Recording Start Failure: This event is sent when a publisher connects to the stage, but recording fails to start due to errors (e.g., the S3 bucket does not exist or is not in the correct region). The publisher's live stream is not recorded.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Participant Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2024-03-13T22:09:58Z", "region": "us-east-1", "resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Recording Start Failure", "participant_id": "xYz1c2d3e4f", "recording_s3_bucket_name": "bucket-name", "recording_s3_key_prefix": "<stage_id>/<session_id>/<participant_id>/2024-01-01T12-00-55Z" } }
Recording End Failure: This event is sent when the recording ends with failure, due to errors encountered during recording (e.g., if the attempt to write a master playlist fails). Some objects may still be written to the configured storage location.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Participant Recording State Change", "source": "aws.ivs", "account": "123456789012", "time": "2024-03-13T22:19:04Z", "region": "us-east-1", "resources": ["arn:aws:ivs:us-west-2:aws_account_id:stage/AbCdef1G2hij"], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Recording End Failure", "participant_id": "xYz1c2d3e4f", "recording_s3_bucket_name": "bucket-name", "recording_s3_key_prefix": "<stage_id>/<session_id>/<participant_id>/2024-01-01T12-00-55Z" "recording_duration_ms": 547327 } }
Examples: Stage Update
Stage update events include an event name (which classifies the event) and metadata about the event. The metadata includes the participant ID which triggered the event, the associated stage and session IDs, and the user ID.
Participant Published: This event is sent when a participant begins publishing to a stage.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Stage Update", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-23T20:12:36Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij" ], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Participant Published", "user_id": "Your User Id", "participant_id": "xYz1c2d3e4f" } }
Participant Unpublished: This event is sent when a participant has stopped publishing to a stage.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Stage Update", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-23T20:12:36Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij" ], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Participant Unpublished", "user_id": "Your User Id", "participant_id": "xYz1c2d3e4f" } }
Participant Publish Error: This event is sent when a participant's attempt to publish to a stage failed.
{ "version": "0", "id": "12345678-1a23-4567-a1bc-1a2b34567890", "detail-type": "IVS Stage Update", "source": "aws.ivs", "account": "123456789012", "time": "2020-06-23T20:12:36Z", "region": "us-west-2", "resources": [ "arn:aws:ivs:us-west-2:123456789012:stage/AbCdef1G2hij" ], "detail": { "session_id": "st-ZyXwvu1T2s", "event_name": "Participant Publish Error", "event_time": "2024-08-13T14:38:17.089061676Z", "user_id": "Your User Id", "participant_id": "xYz1c2d3e4f", "error_code": "BITRATE_EXCEEDED" } }
