The event bus, realtime, and webhooks

An application grows a particular kind of mess: one thing happens, and five systems have to hear about it. An order is placed, so write the audit record, push to the open dashboard, send the webhook, queue the receipt, update the cache. Every one of those is a line in the handler, and the sixth is the one somebody forgets.

This chapter is the alternative: the handler says what happened, once, and anything interested listens.

The problem, in the framework's own history

Before the bus existed, a generated handler called the audit logger and nothing else. Webhooks, realtime and background jobs all existed, and *none of them was ever fired by generated code*. Dispatching a webhook meant hand-writing the call in every handler, for every operation, on every resource.

Forgetting one produced no error at all. Just a subscriber that never heard anything, which is the worst failure mode there is: silent, and only noticed by the customer whose integration stopped working.

events.Emit(ctx, events.Created{
    Resource: "order", ID: order.ID, Actor: actor,
})

One line in the handler. The audit log, outbound webhooks and realtime clients are now subscribers rather than things somebody has to remember to call.

Three deliveries, and choosing between them

const (
    Sync Delivery = iota
    Async
    Durable
)

• Sync
• Runs inline, before the handler responds. For work that must be part of the request
• Async
• Runs on the bus's worker pool after the response. For anything with a network call
• Durable
• Through the transactional outbox: at least once, retried, surviving restarts

Sync is for the audit record: it needs the request context and should be written before the caller is told the write succeeded. A slow Syncsubscriber is a slow endpoint, and that is the whole cost model.

Async is for the webhook endpoint that takes four seconds. The API must not take four seconds because somebody else's server is slow.

Durable is for work another module depends on. If losing the event would leave two systems disagreeing, it is durable.

The outbox, and the choice it removes

Durable delivery exists because of a problem with two halves, and doing the obvious thing gets one of them wrong whichever order you pick.

Publish, then commit. The publish succeeds, the commit fails, and a webhook has announced an order that does not exist. Downstream systems act on it, and there is nothing to reconcile against because the row was never written.

Commit, then publish. The commit succeeds, the process is killed before the publish, and the order exists with nobody told. Nothing is logged anywhere, because from the process's point of view nothing failed.

The outbox removes the choice:

BEGIN
  INSERT INTO orders ...
  INSERT INTO outbox_messages ...
COMMIT

The message is written in the same transaction as the business data, so it commits or rolls back with it. A relay reads committed messages and delivers them afterwards. Either both happened or neither did.

The cost is honest and must be stated: delivery is at least once, not exactly once. A message can be delivered twice if the process dies between the send and the status update. Consumers have to be idempotent, which is what a dedup key on the receiving end is for, and which is the same discipline chapter forty three asked for.

Realtime: channels, not just users

The hub can address a user, everybody, or a named channel. Channels are the one that makes a real interface possible:

socket.send(JSON.stringify({
  action: "subscribe",
  channel: "invoice.42",
}))

The server answers subscribed, subscription_error or unsubscribed, each naming the channel, and server code publishes to the name:

hub.Publish("invoice.42", payload)

Every subscriber on every replica receives it, which is the part that is tedious to build: a second instance of your API has to reach clients connected to the first, so the hub has a backplane.

Without channels, a page showing one invoice had no way to hear about that invoice without every event for that user being pushed at it, which is a real cost on a busy account.

When WebSockets do not arrive

Some platforms do not pass a WebSocket upgrade through to the application. One managed host strips Connection: upgrade before the container, and it is not alone: a corporate proxy, an older load balancer, or an API gateway configured for plain HTTP all do the same.

The failure is unpleasant: the handshake fails, the client's reconnect loop retries forever, and live updates silently never arrive. Nothing errors in a way anybody sees.

So there is a Server-Sent Events fallback. SSE is plain HTTP with a response that never ends, so it survives all of that.

• WebSocket
• Two-way, lower latency, needs the upgrade to survive the network
• SSE
• Server to client only, plain HTTP, reconnects by itself

For dashboards, notifications and live lists, which is most of what an application needs, SSE is enough. Reach for WebSockets when the client needs tosend continuously: a cursor position, a drawing, a chat typing indicator.

Webhooks, outbound

grit plugin add webhooks

That wires outbound, Standard-Webhooks-signed deliveries with retries, a delivery log and manual replay. Core already verifies incoming webhooks; this sends outgoing ones, which is the opposite direction and a different problem.

What matters when you are the one sending:

Sign every delivery. The receiver has to know it was you. Standard Webhooks is a published convention for the headers and the signature, which beats inventing your own and documenting it badly.

Include an ID and a timestamp. Together they let a receiver reject replays and deduplicate retries, which they will need because you are delivering at least once.

Retry with backoff, and keep a log. Somebody will ask "did you send it", and the answer has to be a record with a status code, not a shrug.

Make replay a button. Integrations break on the other side. A delivery log with a replay action turns a support conversation into one click.

audit     Sync      writes the ledger entry
realtime  Async     publishes to "invoice.<id>"
mail      Async     queues the receipt
webhook   Durable   notifies the accounting integration

Assignment

Commit your work with the message Events - Assignment One, exactly as written, so the leaderboard can score it.