An order page can need an update at the same time as your database. A webhook can trigger the database change. Your server can then publish the resulting state to connected screens.
Bird Realtime delivers updates over WebSockets.
What are channels, members and connections?
A channel groups subscriptions. A connection is one open WebSocket. A member is an authenticated identity shared with other subscribers.
A presence channel shares which members are subscribed. One member can use several connections, such as separate browser tabs.
Bird creates a channel when its first connection subscribes and removes it after the last one leaves. You publish to the channel name without creating a separate channel resource.
Each connection receives an identifier. Your backend uses it to approve a private subscription. A publish can exclude that connection to avoid echoing its own update.
If one member opens three tabs, those tabs can create three connections under one member identity. Presence reports the member joining on the first connection and leaving after the last connection closes. Closing the middle tab therefore does not remove that member from the list.
Who is allowed to subscribe?
The channel's prefix determines whether a subscription needs authorization from your backend.
You choose a Bird channel name from 1 to 164 characters, using letters, digits and _ - = @ , . ;. Include the prefix in that length so a generated private name stays within the limit.
| Name prefix | Access |
|---|---|
| No private or presence prefix | Public to clients holding the app key. |
private- | Your backend approves and signs each subscription. |
presence- | Your backend approves the subscription and supplies the member identity shared with subscribers. |
private-encrypted- | Private access with event contents encrypted using a key you control. |
The app key appears in client code, so an obscure public channel name does not protect confidential data. Keep the app secret on your server and use it to sign subscription approvals.
For a private subscription, the client sends its connection identifier and channel name to your authorization endpoint. Your server checks access before returning the signature. That endpoint authorizes access. It does not receive each published event as a webhook would.
What does the difference mean in practice?
Use webhooks for recoverable work on your server. Use pub/sub for updates to connected clients.
A Bird webhook sends an event to an HTTPS endpoint you operate. Retries span roughly 27.5 hours, with waits adjusted by random variation, receiver overload and requested delays. That window gives your receiver time to recover. Missed-event replay can recover deliveries that remain unsuccessful.
A Realtime channel sends your published event to subscribed clients. A disconnected client can miss it. A cache channel can supply its latest event to a new subscriber while that event remains cached. It does not keep the intervening event history.
Keep confidential server-side processing behind your webhook receiver. Publish only the state that the channel's authorized clients may see.
Webhook event types come from Bird's catalog, such as email.delivered. With Realtime, you choose your application's event name when publishing. The event name accepts 1 to 200 characters. The prefixes bird: and bird_internal: are reserved and cannot name your application events.
Clients also receive protocol events about subscription success, member changes and connection counts. Those events describe the connection or channel itself rather than your application's order or message.
How do I use them together?
Use the webhook's stored event to drive a Realtime update for connected clients.
Receive the business event on your server. Update durable state before publishing. Then publish the state that connected clients need.
For an order page, the webhook can trigger a database update. Your server then publishes the updated order state so the customer's page changes without a refresh.
Keep that database state readable after reconnecting because a disconnected client can miss publications. Webhooks, polling or streaming compares the recovery choices.
Realtime also has its own webhooks for channel occupancy and member arrivals or departures. Configure these through the dashboard rather than the public webhooks API.
Realtime overview covers client connections. Webhooks covers requests delivered to your server.
In short
A channel can have many subscribers.
A webhook request goes to one registered endpoint. A publication goes to clients subscribed to its channel.
Private subscriptions need backend approval.
The app key appears in client code. Private and presence prefixes require a signature from your server.
Members can have several connections.
A member using three tabs joins presence on the first connection and leaves after the last connection closes.
Combine delivery recovery with a connected view.
Use webhook recovery for server events and stored state to restore a Realtime view after disconnection.