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 needsiam:PassRoleon it. Every delivery is authorized as the role and recorded in the audit log underassumed-role/<role>; take the permission away from the role and its deliveries fail withAccessDenied(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;inputsends a constant text;inputTransformerfills 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 aftermaxEventAgeSeconds(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-createdTerraform: 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}/cancelstops 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_monthat €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
retentionDaysare 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, dimensionsEventBusNameandRuleName:MatchedEvents,Invocations(attempts),FailedInvocations,InvocationsSentToDlq,DroppedInvocations. Put an alarm onFailedInvocationsto 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.