Eventing & async work
When one service needs to tell another that something happened — a file was uploaded, an invoice was paid, a rule fired — it publishes an event. Other services subscribe.
What you'll learn
- Why we use events for cross-service work
- The delivery guarantee (at-least-once)
- How to publish and consume events from a service
Why events
Synchronous service-to-service calls are easy to write but they create coupling:
- If service B is slow, service A waits.
- If service B is down, service A errors.
- Service A has to know about service B at all.
With events, service A publishes "something happened" and walks away. Service B (and C, D, E) read the event when they're ready. A doesn't care who's listening or whether anyone is.
The platform's eventing layer
Cross-service events use a durable streaming bus with at-least-once delivery and consumer groups.
// Publish (from a service or plugin)
await events.publish('file.uploaded', {fileId, workspaceId, uploadedBy});
// Consume (in another service)
events.consume('file.uploaded', 'thumbnail-worker', async (event) => {
await generateThumbnail(event.fileId);
});
publishwrites to a named event stream.consumereads via a consumer group — multiple workers share the load.
Delivery guarantees
| Guarantee | Yes / No |
|---|---|
| At-least-once delivery | ✅ Yes |
| Exactly-once delivery | ❌ No — design consumers to be idempotent |
| Ordering within a key | ✅ Yes, within a single Stream partition |
| Cross-stream ordering | ❌ No |
Always make consumers idempotent. A retry of the same event should produce the same result as the first delivery.
Common patterns
| Pattern | How |
|---|---|
| Background work after a sync API call | Publish event from the resolver, consume in a worker |
| Fan-out to many consumers | Multiple consumer groups on the same stream |
| Cross-tenant signal | Always include tenantId in the event payload; consumer filters |
| Schedule a job for later | Use the scheduler module |
Operational notes
- Streams are durable but not infinite — set retention per stream
- Dead-letter queue (DLQ) handling is built into the SDK: events that fail N times move to a
:dlqstream - Monitor consumer lag via metrics shipped by the SDK
Next steps
- Scheduler / Jobs
- Webhooks — outbound events to third parties