Event Bus

The Event Bus lets your app announce that something happened — an order was created, a user signed up — and have that single announcement delivered to every interested route at once. You publish one event to a topic; each route on that topic receives its own copy and delivers it to its target. Open Backend → App Services → Event Bus to manage it.

Topics and routes are per environment. Publishing to the orders topic in development never reaches routes in production.

The panel calls these connections routes. The underlying GraphQL API still names the operations after the older term, subscription (createSubscription, subscriptions, and so on) — see the reference if you’re calling the API directly.

The three pieces

Piece	What it is
Topic	A named channel you publish events to (e.g., `orders`, `users`).
Event	A single announcement: an event type (e.g., `orders.created`) plus a JSON payload.
Route	A rule attached to a topic that says “when an event matches this filter, deliver it here” — to a queue, a REST endpoint, or GraphQL.

One topic can have many routes, and each gets an independent copy of every matching event. That independence is the whole point: a slow or failing route never affects the others.

Topics

The Event Bus landing view lists your topics in a table — Name, Events (24 h), Routes, and Failed (the number of failing deliveries, so an unhealthy topic stands out at a glance) — plus a per-row actions menu. Creating a topic needs only a name (retention lives under Advanced settings).

Event Bus panel topic list with the Name, Events (24 h), Routes, and Failed columns and the New event button

Create a topic

Click New event, give it a name, and create it. The button is labeled “New event,” but what it creates — and what the drawer calls it throughout — is a topic: “the publish point that routes connect to.” The infrastructure is provisioned automatically for this environment.

Open the topic

Click the topic to open its detail, which has four tabs: Routes, Tests, Connect, and Activity.

Add a route (the two-step wizard)

The route wizard is the heart of the Event Bus. It answers two questions.

Step 1 — Which events?

Choose which events this route reacts to:

Mode	Matches	Example
All	Every event on the topic.	`orders.created`, `orders.shipped`, …
An exact type	Only the type you name.	only `orders.created`
Pattern	A single-segment wildcard.	`orders.*` matches `orders.created` and `orders.shipped`

Route wizard Step 1 — the three filter modes (All / An exact type / Pattern), with the event type field revealed for "An exact type"

Step 2 — Where should it go?

Pick a target: Queue, REST, or GraphQL.

Queue

Deliver each matching event into one of your existing queues (or create one inline), to be processed by a worker in the background.

REST

Deliver to an external HTTPS endpoint you own. Internal delivery to your own REST API isn’t available yet — that option is shown but disabled (“coming soon”).

GraphQL

Deliver to your own project’s GraphQL API (the default), or to an external GraphQL endpoint with a mutation template you write.

Target: Queue

Select one of your existing queues in the same environment (or create one inline). Each routed queue receives its own copy of every matching event — this is the classic fan-out then process pattern covered in Using them together. Delivery attempts and the dead-letter queue for this path are configured on the queue itself, not on the route.

Target: REST

REST routes currently deliver to an external service only — “My archie-core API” is shown as an option but disabled while that path is built. You provide:

Endpoint URL — must be HTTPS and publicly reachable. It can include dynamic parameters filled in from each event’s payload at delivery time — {field}, [field], and :field are all replaced by the matching top-level field. For example https://api.partner.com/orders/{orderId}/status with payload { "orderId": 42 } delivers to …/orders/42/status.
Method — POST (default), or another verb from the dropdown.
Signing secret (HMAC) — generated automatically when you save and shown once; used to sign every delivery (HMAC-SHA256) so your receiver can verify it came from Archie.
Token / API key (optional) — sent as Authorization if your endpoint needs it.
Custom headers — additional name/value pairs sent on every delivery, encrypted at rest; only the names are shown afterward.
Delivery attempts — 1–20, per route. Once exhausted, the event is parked in this route’s own dead-letter queue — each endpoint route has one, separate from any queue’s.

Target: GraphQL

Choose where it runs:

My archie-core API (internal, default) — search-select an existing mutation from your project’s own schema (the same one the GraphQL API Explorer uses) instead of writing one by hand. You still provide a Token / API key, used as the Authorization for that mutation call — internal delivery is not secret-free, unlike a queue target.
External endpoint — deliver to a GraphQL endpoint you don’t own. You write the mutation yourself; each event field arrives as a $<field> variable, and $event (full payload) and $payload (event + metadata) are also available. The endpoint URL, signing secret, optional token, and delivery attempts work the same way as the REST target.

New route panel with an external endpoint target selected — Endpoint URL, Signing secret (HMAC), Token / API key, and Delivery attempts

The external signing secret is displayed only at creation time. If you lose it, rotate it by recreating the route. Verify the signature on your side before trusting a delivery.

The routes list

Each topic’s Routes tab lists every route with its filter, type, target, delivery-attempts setting, and an Active toggle plus a delete action:

Topic Routes tab listing a route with its Filter, Type, Target, Delivery, and Active columns

Column	What it shows
Filter	The event type or pattern this route matches.
Type	The target kind — Queue, REST, or GraphQL.
Target	The queue name or endpoint the route delivers to.
Delivery	Delivery attempts for endpoint routes; `—` for queue routes (configured on the queue instead).
Active	Pause or resume delivery without deleting the route. Paused routes stop receiving new events until switched back on.

Publish a test event

The Tests tab lets you fire an event by hand to see the whole chain work end to end:

Topic Tests tab — Event type and Payload (JSON) fields with the Publish button

Choose an event type

Type an event type, e.g., orders.created.

Write the payload

Provide a JSON payload in the editor.

Publish

Click Publish. Archie confirms with the message ID once it’s accepted — check the routes it should reach (a queue’s Pending count, or the Activity tab for endpoint targets) to confirm delivery.

Connect your app to a topic

The Connect tab gives you the GraphQL endpoint and a ready-to-paste snippet for publishing from your own code — the same pattern as a queue’s connect panel, with GraphQL as the default tab and REST (curl) as the second:

Topic Connect tab with the GraphQL endpoint and a copyable publishEvent snippet

mutation {
  publishEvent(
    topic: "orders"
    eventType: "orders.created"
    body: "{\"orderId\":\"A-1024\",\"total\":51.25}"
    # dedupKey: "order-A-1024"   # optional: suppress duplicates
  ) {
    messageId
  }
}

Watch deliveries in Activity

The Activity tab is your audit trail of what actually happened for endpoint routes (REST and GraphQL). Queue routes don’t produce delivery rows here — instead, watch the Pending count and error list on the destination queue.

Topic Activity tab, empty state: "No deliveries recorded yet"

Once a REST or GraphQL route has delivered at least once, this tab fills in with the delivery history — the event, the status returned, and how many attempts it took. Retried automatically with increasing back-off; exhausted deliveries land in that route’s own dead-letter queue.

Common questions

What's the difference between an event type and a topic?

A topic is the channel (e.g., orders). An event type is the specific thing that happened on it (e.g., orders.created). Routes filter by event type within a topic.

Do all routes get the event at the same time?

Each matching route gets its own copy, delivered independently. If one route is slow or failing, the others are unaffected.

When should I deliver to my own API vs an external endpoint?

Use GraphQL → My archie-core API when the reaction is a write in your own project — no URL to manage, though you still need a token. Use an external endpoint (REST or GraphQL) when you’re notifying a system outside Archie that you own. Note that REST currently only supports external delivery; internal REST delivery is coming.

A route shows as failing — what do I check?

Open Activity and read the status codes for that route (endpoint routes only — queue routes show their health on the queue itself). A 4xx usually means the target rejected the request (auth, validation); a 5xx or timeout usually means the target was unavailable. Fix the cause; the route retries automatically up to its configured delivery attempts.

Can I temporarily stop a route without losing it?

Yes — switch its Active toggle off in the Routes list. It stops receiving new events and keeps its configuration and history; switch it back on to resume.

Using them together

Fan an event out to several queues and process each copy in the background.

Reference & FAQ

Operations, limits, statuses, and troubleshooting.

Home

Blueprint

Design

Frontend

Backend

Assets

The three pieces

Topics