Skip to content

AWS EventBridge cross-account push — operator playbook

Plan 117 adds a second AWS connection subtype: eventbridge. This playbook walks the operator through everything needed to turn it on for a tenant.

Prerequisites

  • cp-api ≥ release with Plan 117 deployed.
  • Migration 0047_connection_eventbridge applied (broadens subtype enum to {oauth_refresh, wif, assume_role, eventbridge} and adds the EventBridge metadata columns).
  • A platform-admin session (the bus-provisioning endpoint is platform-admin gated).
  • Our AWS account's account number, with permissions to call: events:CreateEventBus, events:PutPermission, events:PutRule, events:PutTargets, and the matching delete ops.

One-time operator setup

  1. Deploy the receiver Lambda in our AWS account. Follow docs/operations/aws-eventbridge-receiver-deployment.md.
  2. Provision the webhook HMAC secret: in cp-api /admin/setup, click "Generate & provision" on the row aws_eventbridge_webhook_secret. The secret is bound to the cp-api Container App as AWS_EVENTBRIDGE_WEBHOOK_SECRET. Copy the same KV-version value into the receiver Lambda's WEBHOOK_HMAC_SECRET env var.
  3. Set the operator-side env vars on cp-api:
  4. AWS_EVENTBRIDGE_RECEIVER_LAMBDA_ARN — the receiver Lambda ARN.
  5. AWS_EVENTBRIDGE_OUR_ACCOUNT_ID — our 12-digit AWS account number.
  6. AWS_EVENTBRIDGE_REGION — us-east-1 in v1 (cross-region supported for customer-side rules, but our bus lives in us-east-1).

Per-tenant onboarding

  1. Customer creates an AWS connection with subtype eventbridge (Connections page → "Connect AWS" → "EventBridge push (new)" tab; supplies their 12-digit AWS account number).
  2. Operator runs POST /admin/connections/{connection_id}/provision-eventbridge from a platform-admin session. The endpoint:
  3. Calls events:CreateEventBus to create secruna-customer-{tenant_id} in our account.
  4. Calls events:PutPermission to grant the customer's account events:PutEvents on the new bus.
  5. Calls events:PutRule + events:PutTargets to forward matched events to the receiver Lambda.
  6. Stamps eventbridge_bus_arn / eventbridge_rule_arn / eventbridge_provisioned_at on the connections row.
  7. Emits audit platform.aws_eventbridge.bus_provisioned.
  8. Returns the bus_arn plus a customer-facing CloudFormation snippet + IAM policy template.
  9. Operator emails the customer the customer-facing payload — see docs/customer/aws-eventbridge-onboarding.md. The customer applies the CloudFormation snippet in their account to create the forwarding EventBridge rule.

Deprovision

DELETE /admin/connections/{connection_id}/eventbridge-bus (platform admin). Tears down the AWS-side rule + permission + bus in order, clears the columns on the connection row, and emits audit platform.aws_eventbridge.bus_deprovisioned.

Rotation

POST /admin/setup/aws-eventbridge-webhook-secret/rotate-secret mints a fresh HMAC secret + restarts cp-api. The operator must paste the new value into the receiver Lambda's WEBHOOK_HMAC_SECRET env var within the cp-api restart window — webhooks signed with the old secret will start failing 401 once the new env var lands on the running revision.

Observability

  • /connections/{id}/aws-eventbridge-stats (org-admin) — last delivery, 24h count, copyable receiver URL.
  • Audit log filters:
  • aws_eventbridge.received — happy path.
  • aws_eventbridge.ignored — known event but no matching connection / unknown CloudTrail event name.
  • aws_eventbridge.rejected — signature mismatch, malformed JSON, missing account id.
  • aws_eventbridge.account_mismatch — defence-in-depth flag (sender account ≠ routed connection's remote_tenant_id).
  • structlog events: aws_eventbridge_webhook.*, aws_eventbridge.provision.*, aws_eventbridge.deprovision.*.

Troubleshooting

Symptom Likely cause Fix
503 aws_eventbridge_webhook_secret_not_configured Operator hasn't run /admin/setup provision yet. Provision the secret via /admin/setup.
401 signature_mismatch Receiver Lambda + cp-api env vars are out of sync after a rotation. Re-sync the Lambda's WEBHOOK_HMAC_SECRET to the latest cp-api value.
403 account_mismatch Bus is targeting our Lambda but the customer's EventBridge rule was provisioned against a different account number. Customer recreates the forwarding rule from the right AWS account.
202 ignored reason connection_not_found Webhook receiver didn't find an active AWS-eventbridge connection for the routing tenant + sender account. Verify connections.subtype='eventbridge' and remote_tenant_id matches the sender account.