Event bus

React to API calls, alarms, failed schedules and deployments; your own events; rules to queues, functions and HTTPS.

An event bus tells your code when something happens. Every organization has a default bus that the platform fills by itself: every successful API call of every service (an instance was created, a bucket deleted, a role changed), every alarm that changes state, every scheduled invocation that fails, every deployment that goes live or fails. You can add custom buses for your own events.

A rule watches a bus. Events that match its pattern go to its targets: a queue, a function, or an HTTPS endpoint. Each delivery is retried with backoff and, when it keeps failing, sent to a dead-letter queue. Every delivery is visible: which event, which target, each attempt and what the target answered.

Deutsche Cloud event buses work like Amazon EventBridge: the same event envelope and the same pattern language, so patterns you already have read the same.

You want Use
Run code when someone creates, changes or deletes things a rule on the default bus matching EWS API Call
Page someone, open a ticket or scale when an alarm fires a rule on Alarm State Change
Clean up after a failed nightly job a rule on Scheduled Invocation Failed
Act before a budget is exceeded a rule on Budget Threshold Crossed (kind forecast)
Tell a chat channel a deployment went live or failed a rule on Deployment State Change with an HTTP target
Hear when a backup fails or a certificate will not renew a rule on Backup State Change / Certificate Renewal Failed
Process again what happened while your consumer was down an archive on the bus, then a replay into the rule
Fan your own application's events out to several services a custom bus, PutEvents, one rule per consumer
Something on a clock the scheduler
A full export of everything, for auditors audit log destinations

Events

Every event has the same envelope:

{
  "version": "0",
  "id": "6f1c2a9e-0d1b-4c55-9a7e-3b1f0c2d4e5f",
  "detail-type": "EWS API Call",
  "source": "ews.ec2",
  "account": "<your organization id>",
  "time": "2026-11-12T10:15:00.000Z",
  "region": "de1",
  "resources": ["rn:ews:de1:<org>:ec2:instance/i-0a1b2c3d"],
  "detail": { "...": "..." }
}

id is unique per event and stays the same on every retry: use it to ignore a delivery you have already handled. region is empty for API calls to services without a region (IAM, DNS, …).

What arrives on the default bus

source detail-type When
ews.<service> EWS API Call every successful write of that service (ews.ec2, ews.s3, ews.iam, ews.queue, …)
ews.monitoring Alarm State Change an alarm moved between OK, ALARM and INSUFFICIENT_DATA
ews.scheduler Scheduled Invocation Failed a schedule's invocation failed after its retries, or was dead-lettered
ews.deploy Deployment State Change a deployment went live or failed
ews.billing Budget Threshold Crossed a budget reached a threshold, by actual spend or by its month-end forecast
ews.sandbox Sandbox Pool Scaled an autoscaled warm pool changed its size
ews.ec2 Instance State-change Notification an instance changed state, whoever moved it (API, reconciler, auto scaling, provider)
ews.rds, ews.mysql, ews.cache, ews.ec2 Backup State Change a database backup, cache snapshot or volume snapshot completed or failed
ews.lb, ews.deploy, ews.cdn Certificate Renewal Failed a certificate in use could not be renewed (Certificate Issuance Failed for a new one)
ews.functions Function Errors a function answered 5xx, failed to start or timed out (summed, at most one a minute)
ews.functions Function Invocation Failed an invocation from the platform never reached the function (no host, host unreachable)

An EWS API Call event is made from the audit log entry of that call, so its detail says what the audit log says:

{
  "eventSource": "ec2",
  "eventName": "RunInstances",
  "action": "ec2:RunInstances",
  "userIdentity": { "type": "session", "principal": "alice", "accessKeyId": null },
  "sourceIPAddress": "203.0.113.9",
  "resource": { "type": "ec2:instance", "id": "i-0a1b2c3d", "rn": "rn:ews:de1:…" },
  "requestParameters": { "body": { "name": "web-1", "instanceType": "performance-2" } },
  "responseStatus": 201,
  "responseElements": { "id": "i-0a1b2c3d" },
  "auditSeq": 1042
}

For a call that creates something, resources names what it created (rn:ews:de1:<org>:ec2:instance/i-0a1b2c3d), then the parent it was made in when there is one (a snapshot's volume) — never the …:ec2:* wildcard the call was authorized on.

Only calls that were allowed and succeeded become events; reads, denials and failed calls do not (denials are in the audit log and its destinations). Events arrive within a few seconds of the call. Deliveries the bus makes itself (a target sending to a queue) do not become events again, so a rule cannot loop on itself.

Alarm State Change: detail.alarmName, detail.state.value, detail.state.reason, detail.previousState.value, detail.resourceType, detail.resourceId, detail.metric. Scheduled Invocation Failed: detail.scheduleName, invocationId, status (failed or dead_lettered), errorCode, error, attempts, scheduledTime, targetType. Deployment State Change: detail.appId, deploymentId, state (live or failed), error. Instance State-change Notification (AWS's field names; the detail-type drops the service name): detail.instance-id, name, state (pending, running, stopping, stopped, shutting-down, terminated), previous-state, reason when it moved because something failed. Backup State Change: detail.resourceId (the database, cache or volume), resourceName, backupId, kind, state (completed or failed), error, sizeBytes. A backup reported twice is one event. Certificate Renewal Failed: detail.resourceId, resourceName, domains, error, notAfter and daysLeft of the certificate still served. Certificate Issuance Failed is the same without notAfter, for a name that has no certificate yet. Function Errors: detail.functionName, functionId, errors, requests, periodStart, periodEnd — the first errors at once, then one event a minute with the sum while they go on. Function Invocation Failed: detail.functionName, functionId, status (502 or 503), error, path. Budget Threshold Crossed: detail.budgetId, budgetName, kind (actual or forecast), thresholdPercent, spend, forecast, amount, percent, currency, period, scope; once per budget, period, threshold and kind (cost explorer). Sandbox Pool Scaled: detail.poolId, poolName, from, to, desired (before the host's room capped it), reason (sandboxes).

The console's rule form lists every platform event with a pattern to start from (GET /events/api/catalog), and tests your pattern against your organization's recent API calls as you type.

Patterns

A pattern is a JSON object shaped like the event. Each field lists what it may be; an event matches when every field in the pattern matches.

{
  "source": ["ews.ec2"],
  "detail-type": ["EWS API Call"],
  "detail": {
    "eventName": ["RunInstances", "TerminateInstances"],
    "userIdentity": { "principal": [{ "anything-but": "ci-bot" }] }
  }
}
Matcher Matches
"text", 12, true, null exactly that value
{ "prefix": "rn:ews:de1:" } a string starting with it
{ "suffix": ".png" } a string ending with it
{ "equals-ignore-case": "alarm" } the string, in any case
{ "anything-but": "OK" } / ["a", "b"] a value that is none of them (not a missing field)
{ "anything-but": { "prefix": "test-" } } a string not starting with it
{ "exists": true } / false the field is there / is not there
{ "numeric": [">=", 500, "<", 600] } a number in the range (<, <=, =, >, >=)
{ "wildcard": "rn:ews:*:ec2:instance/*" } a string matching it: * is any run of characters, \* a literal star

A list matches when any of its entries matches. When the event's field is a list (like resources), the field matches when any of its elements does. Nested objects match inside the field. A wildcard has at most five *, never two in a row.

$or matches when any of its patterns does, at any level, alongside the other fields:

{
  "source": ["ews.ec2"],
  "$or": [
    { "detail-type": ["Instance State-change Notification"] },
    { "detail": { "eventName": ["TerminateInstances"] } }
  ]
}

Not supported yet: cidr — a rule using it is refused, so nothing silently never matches. Test a pattern without saving it: POST /events/api/test-pattern.

Targets

A rule has up to five targets. Each gets every matching event.

Target Sends Success Role needs
queue a message (body = the event; attributes dcloud-event-id, dcloud-rule-name, dcloud-event-source, dcloud-event-detail-type, dcloud-event-bus, each also as ews-…) the message is stored queue:SendMessage
function POST to the function (path, default /), JSON body a 2xx answer functions:InvokeFunction
http POST/PUT/PATCH to an https URL on a public address, signed a 2xx answer — (only for a DLQ)
rabbitmq a persistent message to an exchange of a managed RabbitMQ broker (routingKey, default the event source) routed and confirmed rabbitmq:PublishMessage
kafka a record to a topic of a managed Kafka cluster (key: event id (default), source, detail-type or none) acked by all ISR kafka:PublishMessage
  • Role: queue and function targets act as an IAM role you name (roleName), not as you. Saving the rule needs iam:PassRole on it. Every delivery is authorized as the role and recorded in the audit log under assumed-role/<role>; take the permission away from the role and its deliveries fail with AccessDenied (within 10 seconds: a role's policies are cached that long), visibly, without retries.
  • What is sent: the whole event by default; inputPath: "$.detail" (or $.resources[0]) sends a part of it; input sends a constant text; inputTransformer fills a template from the event (below). One of the three per target.
  • Retries: a failed attempt that may pass next time (an HTTP 5xx, 429 or 408, a timeout, a refused connection, a queue over its limits, no function host yet) is retried with exponential backoff from 5 seconds to at most 15 minutes, up to retryMaxAttempts (default 185) and never after maxEventAgeSeconds (default 24 hours) from when the bus received the event. A 4xx, a denied role, or a target that no longer exists is not retried.
  • Dead-letter queue: when a delivery fails for good and the target has a deadLetterQueue, the bus sends a message there (as the role) with the rule, the target, the attempts, the last error and the whole event.
  • FIFO queues: the message group is messageGroupId (default: the rule name); the deduplication id is the event id and the target id, so a retry is never a second message.

Shaping what is sent: input templates

inputTransformer (EventBridge's InputTransformer) is a template with placeholders in angle brackets:

{
  "inputPathsMap": { "instance": "$.detail.instance-id", "state": "$.detail.state" },
  "inputTemplate": "{\"text\": \"Instance <instance> is <state>\", \"at\": \"<$.time>\", \"tags\": <$.detail.tags>}"
}
Placeholder Is
<$.detail.x>, <$.resources[0]> a path into the event
<name> a path named in inputPathsMap
<ews.events.event.json> the whole event
<ews.events.rule-name>, <ews.events.event-bus-name>, <ews.events.event-id>, <ews.events.replay-name> what they say

When the template is JSON (starts with { or [), a placeholder inside a string is inserted as escaped text, so "Instance <instance> stopped" stays one valid string, and one outside a string as a JSON value ("n": <$.detail.count>). A path that leads nowhere is "" inside a string and null outside. Any other template is plain text. A JSON template that would not be valid JSON is refused when the rule is saved.

Verifying an HTTP delivery

Every rule has a signing secret (GET …/rules/{rule}/signing-secret, an audited read). Requests carry these headers, each also under its name from before the rename, X-EWS-…, with the same value:

Header Value
X-DCLOUD-Signature-256 sha256=<hex HMAC-SHA256(secret, "<timestamp>.<body>")>
X-DCLOUD-Timestamp Unix seconds
X-DCLOUD-Event-Id the event id: your idempotency key
X-DCLOUD-Delivery-Id this delivery (same on every attempt)
X-DCLOUD-Attempt 1, 2, …
X-DCLOUD-Rule-Name, X-DCLOUD-Event-Bus, X-DCLOUD-Event-Source, X-DCLOUD-Event-Detail-Type what they say
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, headers, body) {
  const ts = headers['x-dcloud-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const want = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');
  return headers['x-dcloud-signature-256']
    .split(',')
    .some((sig) => sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)));
}

After POST …/signing-secret/rotate the previous secret keeps signing for 24 hours and both signatures are sent, comma separated.

Sending your own events

dcloud events buses create --name orders
# one --entries per event, up to 10
dcloud events buses put-events --bus orders --entries '{"source":"com.example.shop","detailType":"Order Placed","detail":{"id":"o-1","total":250}}'
POST /events/api/buses/orders/events
Authorization: EWS-ACCESS-KEY EWS1…:…

{ "entries": [ { "source": "com.example.shop", "detailType": "Order Placed",
                 "detail": { "id": "o-1", "total": 250 } } ] }

Up to 10 entries per call, each at most 256 KiB including the envelope. The answer lists each entry's eventId and how many rules it matched, or its errorCode. Sources starting with ews. belong to the platform and are refused. Events sent to a custom bus are kept for 7 days and listed under Recent events.

A rule, end to end

dcloud events rules create default --name instance-created \
  --event-pattern 'source=["ews.ec2"]' \
  --event-pattern 'detail={"eventName":["RunInstances"]}' \
  --targets '{"id":"inventory","type":"queue","queueName":"inventory-updates","roleName":"events-sender","deadLetterQueue":"inventory-dlq"}' \
  --targets '{"id":"chat","type":"http","url":"https://hooks.example.com/ews","inputPath":"$.detail"}'
dcloud events rules deliveries default --rule instance-created

Terraform: dcloud_event_bus, dcloud_event_rule (targets inline, as the API takes them) and dcloud_event_archive.

Archive and replay

An archive keeps the events of one bus — all of them, or those matching its own pattern — whether a rule matched them or not, for retentionDays (1 to 3650, default 90). A replay sends an archive's events from a time window to rules of that bus again. Use it when a consumer was down longer than its retries, when you add a rule and want what already happened, or to rebuild a read model.

dcloud events archives create --name orders-all --event-bus orders --retention-days 365
# … later: what arrived between 08:00 and 09:00, into the rule "billing"
dcloud events replays start --name billing-0800 --archive orders-all \
  --event-start-time 2026-11-14T08:00:00Z --event-end-time 2026-11-14T09:00:00Z --rules billing
dcloud events replays get --replay billing-0800
  • Order: a replay goes through the archived events in the order the bus received them and sends one at a time: the next only when every delivery of the previous one is final. Your targets see the original order.
  • Which rules: one or more rules of the archive's bus, each with its current pattern — narrow a rule and replay to send only part of the history. Disabled rules cannot be replayed into.
  • Marked: a replayed event is the original envelope (same id, time, detail) plus "replay-name": "<replay>"; a template can use <ews.events.replay-name>. Replayed events are not archived again.
  • Retries: a replay delivery is retried at most 3 times within 5 minutes (fewer if the target allows fewer), then goes to the target's dead-letter queue or fails, and the replay moves on — one broken event does not hold the rest for a day.
  • Progress: eventsTotal (archived events in the window when it started), eventsProcessed, eventsReplayed (sent to at least one rule), lastReplayedEventTime; the console shows a bar. POST /events/api/replays/{replay}/cancel stops it after the event in flight. One running replay per archive, five per organization; finished replays are listed for 7 days.
  • Price: what an archive holds, storage.events.gb_month at €0.10 per GB-month, measured daily (an event is its JSON envelope). Archiving and replaying are not charged. The cost explorer lists each archive.
  • Retention: events older than retentionDays are removed daily; lowering it removes the older ones at the next pass. Deleting an archive deletes its events.
  • An archive on the default bus keeps your organization's API activity, so creating, changing, reading or replaying it also needs iam:GetAuditLogs.

Terraform: dcloud_event_archive (a replay is a one-off action, started from the API, CLI, MCP or the console's Archives & replay tab).

Seeing what happened

  • Deliveries (GET …/rules/{rule}/deliveries, console: open a rule): each event, target, status (pending, running, retry_wait, succeeded, failed, dead_lettered, dropped), attempts, the target's answer, the dead-letter message id.
  • Logs: Monitoring → Logs, resource type event_rule, one stream per delivery with each attempt and the answer.
  • Metrics in EWS/Events, dimensions EventBusName and RuleName: MatchedEvents, Invocations (attempts), FailedInvocations, InvocationsSentToDlq, DroppedInvocations. Put an alarm on FailedInvocations to hear about a rule that stopped working.
  • The rule's own changes and its failed deliveries are in its event history; creating and changing rules is in the audit log.

Permissions

Action For
events:ListEventBuses, DescribeEventBus reading buses (and their recent events)
events:CreateEventBus, DeleteEventBus custom buses
events:PutEvents sending events (permitted calls are not audited)
events:ListRules, DescribeRule, ListDeliveries reading rules and what they delivered
events:PutRule, DeleteRule, EnableRule, DisableRule rules; enable/disable alone need only their action
events:PutTargets, RemoveTargets a rule's targets (plus iam:PassRole on each role)
events:TestEventPattern the pattern tester
events:GetRuleSigningSecret, RotateRuleSigningSecret the HTTP signing secret
events:ListArchives, DescribeArchive reading archives and the events they hold
events:CreateArchive, UpdateArchive, DeleteArchive archives
events:StartReplay on the replay, the archive and each rule it sends to
events:ListReplays, DescribeReplay, CancelReplay replays

Buses are rn:ews:de1:<org>:events:event-bus/<name>, rules rn:ews:de1:<org>:events:rule/<bus>/<name> — so rule/default/* covers every rule on the default bus. Archives are …:events:archive/<name>, replays …:events:replay/<name>. A rule or an archive on the default bus delivers your organization's API activity, so creating or changing one (and reading the default bus's events) also needs iam:GetAuditLogs.

Limits

Limit Value
Custom buses per org 10
Rules per bus 100
Targets per rule 5
Event size 256 KiB with the envelope
Entries per PutEvents 10
Retries per delivery 0–185 (default 185)
Maximum event age 60 s – 24 h (default 24 h)
Events kept on a bus 7 days
Archives 10 per bus, 50 per org
Archive retention 1–3650 days (default 90)
Running replays 1 per archive, 5 per org
Rules per replay 10

Delivery is at least once: an event can reach a target twice (a worker that stopped after the target answered and before the answer was written). Use the event id to de-duplicate. Live delivery order is not guaranteed; a replay's is. An event sent with PutEvents reaches a worker within milliseconds (the ingest notifies the workers, Postgres NOTIFY); without that, the workers' poll finds it within half a second.

Did this page help you?