An order update can have two consumers: your database and the customer watching an order page. They need different recovery behavior when a connection drops.
Your database needs a recoverable record of the event. The customer's page may only need the latest order state after it reconnects.
What are the four options?
Bird offers webhooks, Realtime, a dashboard event stream and API reads you can poll.
Use webhooks to receive events on your server. Use Realtime to update connected clients. The SSE stream sends resource changes to a dashboard session. Polling lets your application read resource state on a schedule.
| Mechanism | Direction | Authentication | Recovery after disconnection |
|---|---|---|---|
| Webhooks | Bird sends to your server. | Your receiver verifies a signature with its endpoint secret. | Failed deliveries are retried. Missed events can be replayed. |
| Realtime | Your server publishes to connected clients. | Clients connect with an app key. Private subscriptions need backend authorization. | Reconnecting clients need state recovery. |
| SSE stream | Bird sends resource changes to a dashboard session. | A dashboard session cookie. | Read the resource again for its state. |
| Polling | Your application asks Bird for state. | An API key. | A later read returns resource state, without reconstructing every transition. |
When are webhooks the right answer?
Use webhooks when your server needs to act on events and recover missed deliveries.
You register a publicly reachable HTTPS endpoint. Subscribe it to the event types you need. Your receiver verifies the signature first. It then stores the event. It acknowledges the delivery before slow processing begins.
Bird makes up to eight attempts over roughly 27.5 hours before timing adjustments. That window gives a receiver time to recover from an outage. Missed-event replay provides a further recovery path.
Deduplicate on webhook-id because the same event can arrive repeatedly. Compare event occurrence times before overwriting state because events can arrive out of order.
Failed webhook retries covers recovery limits. Duplicate handling covers storing the event safely before returning success.
When should I use Realtime instead?
Use Realtime when a connected browser or application needs updates as your server publishes them.
A channel is a named destination that clients subscribe to. Your server publishes an event to that name, and subscribed clients receive it over their connections. This can update an order page, a chat conversation or a progress display without a refresh.
Realtime does not replay every event a disconnected client missed. Keep durable state in your database and restore the view after reconnecting.
A cache channel retains its latest event for new subscribers while that cached value remains available. It keeps no event history. If two updates happen while a client is offline, a cached latest value cannot recover the intermediate update.
The app key appears in client code, so a public channel can be read by a visitor holding that key. A channel beginning with private- requires your backend to authorize the subscription. A presence- channel also shares the identities of subscribed members.
Channel names accept 1 to 164 characters using letters, digits and _ - = @ , . ;. The prefix is part of that limit, so include it when validating a generated name.
Realtime also sends webhooks when a channel gains its first subscriber or loses its last. Membership webhooks report which members joined or left. Configure those through the dashboard. Publish/subscribe versus webhooks explains how the two mechanisms fit together.
Does Bird have an SSE endpoint?
Bird has an SSE endpoint, getEventsStream, for authenticated dashboard sessions.
GET /v1/events/stream reports changes to API resources. A notification identifies the resource type, identifier and occurrence time so the dashboard can fetch the resource's data.
The endpoint accepts a dashboard session cookie. It does not accept an API key, so use webhooks or polling for an API-key integration.
When is polling correct?
Use polling when you need resource state, cannot receive incoming requests or have no public event for the change.
Poll to check whether a carrier approved your toll-free number for sending texts. Bird has no public webhook event for that verification decision. Read the verification on a schedule through bird sms tfn verifications get, or the corresponding agent tool. The command operation is outside the public API bundle.
Polling also works for a network that permits outbound requests but cannot expose a receiver. If you only need the present state, reading the resource avoids rebuilding it from past events.
Reads and lists consume rate-limit budgets per acting credential within an organization. Wait before requesting again after an HTTP 429 response. Match the interval to how quickly your application needs to discover a change.
Webhooks, Realtime and rate limits cover configuration for these paths.
Which should I choose?
Choose by who consumes the update and what must survive a disconnection.
- Webhooks when your server must process events with retries and missed-event recovery.
- Realtime when connected screens need updates and can recover from stored state after reconnecting.
- Polling when you need resource state, cannot expose a receiver or have no public event.
- The SSE stream for an authenticated Bird dashboard session.
In short
Choose webhooks for server-side event handling.
Use retries and missed-event replay when your server needs to recover delivery after an outage.
Choose Realtime for connected screens.
Restore the view from stored state when the client reconnects.
Choose polling for resource state.
Poll when you cannot expose a receiver, have no public event or only need the resource's state.
Use SSE for a Bird dashboard session.
The stream requires dashboard session authentication.