Realtime updates

Harly uses Server-Sent Events (SSE) for browser updates because the flow is server-to-client. PostgreSQL remains the source of truth; the stream is a delivery optimization and can be replayed or reconciled.

Client flow

const stream = new EventSource("/api/realtime");

stream.addEventListener("application.stage_changed", (event) => {
  const payload = JSON.parse(event.data);
  queryClient.invalidateQueries({
    queryKey: ["application", payload.applicationId],
  });
});

stream.onerror = () => {
  // EventSource reconnects. Reconcile visible queries after reconnect.
};

The browser should invalidate the smallest affected query rather than call a global router.refresh() after every event.

Reliability model

PostgreSQL is authoritative.
Durable domain events support automation, audit, and webhooks.
Realtime events carry event type, event version, schema version, workspace, sequence, and a compact payload.
The client reconnects automatically and performs a focused reconciliation.
Ephemeral UI events such as candidate.viewed do not need durable domain retention.

Never treat receipt of an SSE event as proof that a mutation committed. Read the affected record from the authenticated API after invalidation.

Event types

The SSE stream emits these event types:

Event type	Payload	When
`application.created`	Application ID, job ID, candidate ID	New application submitted
`application.stage_changed`	Application ID, from stage, to stage	Application moved in pipeline
`application.hired`	Application ID, candidate ID	Application marked as hired
`application.rejected`	Application ID, candidate ID	Application rejected
`candidate.created`	Candidate ID	New candidate profile created
`candidate.updated`	Candidate ID, changed fields	Candidate profile edited
`interview.scheduled`	Interview ID, application ID	Interview created
`interview.canceled`	Interview ID	Interview canceled
`interview.completed`	Interview ID	Interview marked complete
`interview.rescheduled`	Interview ID, old time, new time	Interview time changed
`job.published`	Job ID	Job made public
`candidate.viewed`	Candidate ID, viewer ID	Candidate profile opened (ephemeral)

Ephemeral events like candidate.viewed are not retained in the domain event outbox and cannot be replayed.

Production guidance

One stream per tab

Keep one EventSource connection per browser tab. Multiple streams per workspace waste connections and produce duplicate events.

Invalidate precisely

Invalidate the smallest affected query rather than calling a global router.refresh() after every event.

Monitor health

Track SSE p95 latency and reconnect rates. A broken stream must not block a database mutation or background job.

Handle reconnection

After a reconnect, reconcile visible queries by re-fetching the data that changed during the disconnection window.

Troubleshooting

Symptom	Likely cause	Fix
Events not arriving	Stream disconnected	Check network, proxy timeouts, and `EventSource` readyState
Duplicate events	At-least-once delivery	Deduplicate by event ID in your query invalidation
Stale data after reconnect	Reconciliation not triggered	Re-fetch affected queries on `onopen` after reconnect
Stream blocked by proxy	Proxy timeout too short	Increase proxy read timeout for `/api/realtime`
High memory in browser	Too many listeners	Unsubscribe from events for components no longer mounted

Next steps

Webhooks

Send events to external systems with signed deliveries.

Automations

Trigger internal workflows on domain events.

API overview

Authentication, rate limits, and response formats.

Get started

Tutorials

Using Harly

Deploy Harly

Integrations

Security

API and automation

API Reference

Operations

Realtime updates

Client flow

Reliability model

Event types

Production guidance

Troubleshooting

Next steps

Webhooks

Automations

API overview

​Client flow

​Reliability model

​Event types

​Production guidance

​Troubleshooting

​Next steps

Webhooks

Automations

API overview

Client flow

Reliability model

Event types

Production guidance

Troubleshooting

Next steps