feat(apigatewayv2-integrations): add PutEvents support for EventBridge integration

[jasdeepbhalla]

Issue #35714

Closes #35714

Reason for this change

The CDK currently lacks a high-level L2 construct to enable HTTP API integration with EventBridge PutEvents. Users must manually configure the integration, including IAM roles and parameter mapping, which adds complexity and potential for misconfiguration. This feature simplifies usage and aligns with other existing HTTP API integrations like SQS.

Description of changes

• Added HttpEventBridgeIntegration class extending HttpRouteIntegration.
• Introduced HttpEventBridgeIntegrationProps interface with required parameters: detail, detailType, source; and optional parameters: eventBusName, resources, time, region, traceHeader, invocationRole, description, timeout.
• Automatically creates the IAM role with the necessary permissions if invocationRole is not provided.
• Implements parameter mapping for EventBridge PutEvents API.
• Added unit tests to verify integration behavior.
• Updated documentation to include usage examples.

Example usage:

const stack = new Stack();
const bus = new EventBus(stack, 'Events');
const api = new HttpApi(stack, 'HttpApi');
api.addRoutes({
  path: '/default',
  methods: [apigwv2.HttpMethod.POST],
  integration: new HttpEventBridgeIntegration('defaultIntegration', {
    eventBus: bus,
  }),
});

api.addRoutes({
  path: '/put-events',
  methods: [apigwv2.HttpMethod.POST],
  integration: new HttpEventBridgeIntegration('putEventsIntegration', {
    eventBus: bus,
    subtype: apigwv2.HttpIntegrationSubtype.EVENTBRIDGE_PUT_EVENTS,
  }),
});

Description of how you validated changes

• Added unit tests covering successful integration creation and parameter mapping.
• Manual testing with a sample stack to verify events are sent correctly to EventBridge.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[aws-cdk-automation]

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

[jolo-dev]

Shall we fix the HttpIntegrationSubtype.EVENTBRIDGE_PUT_EVENTS? Otherwise, you could pass another subtype here.

[jasdeepbhalla]

Yeah, that’s another valid approach. Keeping it this way allows us to easily extend support to other subtypes in the future.

If an unknown subtype is provided, we already handle it by throwing an error, so that scenario is covered.

[jolo-dev]

Yeah, I understand.
But from the DX-perspective the developer does not know that only HttpIntegrationSubtype.EVENTBRIDGE_PUT_EVENTS is possible.

Perhaps you could create a new type

type HttpEventBridgeIntegrationSubtype = 'EVENTBRIDGE_PUT_EVENTS'  // then you could use a discreminator to add more events;

export interface HttpEventBridgeIntegrationProps {
  // ..
  readonly subtype?: HttpEventBridgeIntegrationSubtype;
  // ...
}

export class HttpEventBridgeIntegration extends apigwv2.HttpRouteIntegration {
  private readonly subtype: apigwv2.HttpIntegrationSubtype;
  /**
   * @param id id of the underlying integration construct
   * @param props properties to configure the integration
   */
  constructor(
    id: string,
    private readonly props: HttpEventBridgeIntegrationProps,
  ) {
    super(id);
    this.subtype = this.props.subtype;
  }

  public bind(options: apigwv2.HttpRouteIntegrationBindOptions): apigwv2.HttpRouteIntegrationConfig {
    // ...

    return {
      payloadFormatVersion: apigwv2.PayloadFormatVersion.VERSION_1_0,
      type: apigwv2.HttpIntegrationType.AWS_PROXY,
      subtype: apigwv2.HttpIntegrationSubtype[this.props.subtype ?? 'EVENTBRIDGE_PUT_EVENTS'], // <-- this needs to be changes
      credentials: apigwv2.IntegrationCredentials.fromRole(invokeRole),
      connectionType: apigwv2.HttpConnectionType.INTERNET,
      parameterMapping: this.props.parameterMapping ?? this.createDefaultParameterMapping(options.scope),
    };
  }

}

[jolo-dev]

@jasdeepbhalla Ah, you were faster than me :D
Good work. I would have done one thing differently.