Events

Events route a structured notification to every destination that matches. Publish an order-created event once; rules send it to a queue, a function, or both. Use events when producers should not know who consumes the work. Use queue when one worker should own a job.

Status: Preview. See the API action reference for the full command list.

Before you start

• Sign in with skippr-cloud login. See Cloud User Directory.
• Create the destination queue or function first.
• Ensure your policy allows the event operations and access to the target resource.

Route your first event

The following complete flow sends an order.created event to an existing order-jobs queue. Creating the bus, rule, and target is CLI, Terraform, CDKTF TypeScript, or CDKTF Python. Publishing an event is a data-plane call. For provider credentials and the shared cloud provider block, see Terraform and CDKTF.

1. Create the bus

CLI

skippr-cloud events create-event-bus --name orders

Terraform

resource "cloud_event_bus" "orders" {
  name = "orders"
}

CDKTF TypeScript

import { CloudProvider, CloudEventBus } from "@skippr/provider-cloud";

const cloud = new CloudProvider(this, "cloud", { region: "eu-central-1" });

const bus = new CloudEventBus(this, "orders", {
  name: "orders",
  provider: cloud,
});

CDKTF Python

from skippr_cdktf import CloudProvider, CloudEventBus

cloud = CloudProvider(self, "cloud", region="eu-central-1")

bus = CloudEventBus(
    self,
    "orders",
    name="orders",
    provider=cloud,
)

2. Match events with a rule

CLI

skippr-cloud events put-rule --input - <<JSON
{
  "name": "new-orders",
  "eventBusName": "orders",
  "eventPattern": {
    "source": ["app.orders"],
    "detail-type": ["order.created"]
  }
}
JSON

Terraform

resource "cloud_event_rule" "new_orders" {
  name           = "new-orders"
  event_bus_name = cloud_event_bus.orders.name
  event_pattern  = jsonencode({
    source        = ["app.orders"]
    "detail-type" = ["order.created"]
  })
}

CDKTF TypeScript

import { CloudEventRule } from "@skippr/provider-cloud";

const rule = new CloudEventRule(this, "new-orders", {
  name: "new-orders",
  eventBusName: "orders",
  eventPattern: JSON.stringify({
    source: ["app.orders"],
    "detail-type": ["order.created"],
  }),
  provider: cloud,
});

CDKTF Python

import json
from skippr_cdktf import CloudEventRule

rule = CloudEventRule(
    self,
    "new-orders",
    name="new-orders",
    event_bus_name="orders",
    event_pattern=json.dumps({
        "source": ["app.orders"],
        "detail-type": ["order.created"],
    }),
    provider=cloud,
)

3. Attach a queue target

CLI

skippr-cloud events put-targets --input - <<JSON
{
  "rule": "new-orders",
  "eventBusName": "orders",
  "targets": [{
    "id": "order-worker",
    "arn": "arn:cloud:queue:{region}:acme:queue/order-jobs"
  }]
}
JSON

Terraform

resource "cloud_event_target" "order_worker" {
  rule           = cloud_event_rule.new_orders.name
  event_bus_name = cloud_event_bus.orders.name
  target_id      = "order-worker"
  arn            = "arn:cloud:queue:eu-central-1:acme:queue/order-jobs"
}

CDKTF TypeScript

import { CloudEventTarget } from "@skippr/provider-cloud";

new CloudEventTarget(this, "order-worker", {
  rule: "new-orders",
  eventBusName: "orders",
  targetId: "order-worker",
  arn: "arn:cloud:queue:eu-central-1:acme:queue/order-jobs",
  provider: cloud,
});

CDKTF Python

from skippr_cdktf import CloudEventTarget

CloudEventTarget(
    self,
    "order-worker",
    rule="new-orders",
    event_bus_name="orders",
    target_id="order-worker",
    arn="arn:cloud:queue:eu-central-1:acme:queue/order-jobs",
    provider=cloud,
)

Publish a matching event with PutEvents. Check failedEntryCount after PutTargets and PutEvents. A successful HTTP response can still contain per-entry failures.

skippr-cloud events put-events --input - <<JSON
{
  "eventBusName": "orders",
  "entries": [{
    "source": "app.orders",
    "detailType": "order.created",
    "detail": "{\"orderId\":\"ord_123\"}"
  }]
}
JSON

Core concepts

Term	Meaning
Event bus	Named routing boundary. The default bus always exists.
Event	source, detailType, and a JSON string in detail
Rule	Pattern that selects events on one bus
Target	Queue or function ARN that receives matching events

Preview patterns support source and detail-type string arrays. An empty {} pattern matches every event on the bus.

Operations by task

Build routing

Operation	Use it to
CreateEventBus	Create a named bus
PutRule	Create or replace a rule's event pattern without dropping its targets
PutTargets	Upsert queue or function ARNs by target id without dropping siblings
RemoveTargets	Detach targets by id

Publish

Operation	Use it to
PutEvents	Publish one or more entries and inspect per-entry results

Gateway EVENTS_PUT integrations can expose PutEvents from your own Api routes. They do not expose event bus or rule administration.

Inspect and remove

Operation	Use it to
ListEventBuses	List named buses plus default
ListRules / DescribeRule	Inspect rules and patterns
ListTargets	Read the targets attached to a rule
DeleteRule	Delete rule metadata and its targets
DeleteEventBus	Delete an empty named bus

Target and delivery contract

Target	ARN shape	Preview behavior
Queue	arn:cloud:queue:{region}:acme:queue/<name>	Sends a work item
Function	arn:cloud:functions:{region}:acme:function/<name>	Invokes synchronously with the event JSON
Streams topic	Streams targets are not available yet	Rejected by PutTargets

Bus ARNs look like arn:cloud:events:{region}:acme:event-bus/<name>. Rule ARNs look like arn:cloud:events:{region}:acme:rule/<bus>/<name>. PutTargets upserts by target id; it does not replace the whole list. Unsupported target ARNs are returned in failedEntries; they are not ignored, and a failed PutTargets entry does not remove other targets on the rule. DescribeRule returns the rule but not its targets—use ListTargets for those. The default bus cannot be deleted, and a named bus cannot be deleted while rules remain.

PutEvents delivers at least once: a successful HTTP response can still contain per-entry failures, and a retried publish may fan out again. Published events are retained for at most 7 days.

Errors

Code or status	Meaning
ResourceNotFoundException	The bus or rule does not exist
ValidationException	Invalid request, pattern, protected default bus action, or unsupported target
InternalException	Delivery to a matched destination failed
401 / 403	Missing authentication or a policy denial
failedEntryCount	One or more targets or events failed inside an otherwise valid request

Related

• CLI and SDKs
• API actions
• Infrastructure resources
• Terraform and CDKTF
• Queue
• Functions
• Scheduler
• Gateway