Una actualización de pedido puede tener dos consumidores: tu base de datos y el cliente que observa la página del pedido. Necesitan comportamientos de recuperación distintos cuando se pierde la conexión.
Tu base de datos necesita un registro recuperable del evento. La página del cliente puede necesitar solo el último estado del pedido tras reconectarse.
¿Cuáles son las cuatro opciones?
Bird ofrece webhooks, Realtime, un stream de eventos del dashboard y lecturas de API que puedes consultar por polling.
Usa webhooks para recibir eventos en tu servidor. Usa Realtime para actualizar clientes conectados. El stream SSE envía cambios de recursos a una sesión de dashboard. El polling permite a tu aplicación leer el estado de un recurso según un calendario.
| Mecanismo | Dirección | Autenticación | Recuperación tras desconexión |
|---|---|---|---|
| Webhooks | Bird envía a tu servidor. | Tu receptor verifica una firma con su secreto de endpoint. | Las entregas fallidas se reintentan. Los eventos perdidos se pueden reproducir. |
| Realtime | Tu servidor publica a clientes conectados. | Los clientes se conectan con una app key. Las suscripciones privadas requieren autorización del backend. | Los clientes que se reconectan necesitan recuperar estado. |
| SSE stream | Bird envía cambios de recursos a una sesión de dashboard. | Una cookie de sesión de dashboard. | Vuelve a leer el recurso para obtener su estado. |
| Polling | Tu aplicación consulta el estado a Bird. | Una clave de API. | Una lectura posterior devuelve el estado del recurso, sin reconstruir cada transición. |
¿Cuándo son los webhooks la respuesta correcta?
Usa webhooks cuando tu servidor necesite actuar sobre eventos y recuperar entregas perdidas.
Registra un endpoint de HTTPS accesible públicamente. Suscríbelo a los tipos de evento que necesites. Tu receptor verifica primero la firma. Después almacena el evento. Confirma la entrega antes de que comience el procesamiento lento.
Bird realiza hasta ocho intentos en aproximadamente 27,5 horas antes de ajustes de temporización. Esa ventana da tiempo al receptor para recuperarse de una interrupción. La reproducción de eventos perdidos ofrece una vía de recuperación adicional.
Deduplica por webhook-id porque el mismo evento puede llegar repetidamente. Compara las marcas de tiempo de ocurrencia antes de sobrescribir estado, porque los eventos pueden llegar desordenados.
Reintentos de webhooks fallidos cubre los límites de recuperación. Manejo de duplicados cubre cómo almacenar el evento de forma segura antes de devolver éxito.
¿Cuándo debo usar Realtime en su lugar?
Usa Realtime cuando un navegador o aplicación conectados necesiten actualizaciones a medida que tu servidor las publica.
Un canal es un destino con nombre al que los clientes se suscriben. Tu servidor publica un evento en ese nombre, y los clientes suscritos lo reciben a través de sus conexiones. Esto puede actualizar una página de pedido, una conversación de chat o un indicador de progreso sin recargar.
Realtime no reproduce todos los eventos que un cliente desconectado perdió. Guarda el estado duradero en tu base de datos y restaura la vista tras reconectarte.
Un canal de caché retiene su último evento para nuevos suscriptores mientras ese valor en caché siga disponible. No conserva historial de eventos. Si ocurren dos actualizaciones mientras un cliente está desconectado, el último valor en caché no puede recuperar la actualización intermedia.
La app key aparece en el código del cliente, así que un canal público puede ser leído por cualquier visitante que tenga esa clave. Un canal que comienza con private- requiere que tu backend autorice la suscripción. Un canal presence- además comparte las identidades de los miembros suscritos.
Los nombres de canal aceptan de 1 a 164 caracteres usando letras, dígitos y _ - = @ , . ;. El prefijo forma parte de ese límite, así que inclúyelo al validar un nombre generado.
Realtime también envía webhooks cuando un canal obtiene su primer suscriptor o pierde el último. Los webhooks de membresía informan qué miembros se unieron o se fueron. Configúralos desde el dashboard. Publicar/suscribir frente a webhooks explica cómo encajan ambos mecanismos.
¿Tiene Bird un endpoint SSE?
Bird tiene un endpoint SSE, getEventsStream, para sesiones de dashboard autenticadas.
GET /v1/events/stream informa cambios en recursos de API. Una notificación identifica el tipo de recurso, el identificador y la hora de ocurrencia para que el dashboard pueda obtener los datos del recurso.
El endpoint acepta una cookie de sesión de dashboard. No acepta una clave de API, así que usa webhooks o polling para una integración con clave de API.
¿Cuándo es correcto usar polling?
Usa polling cuando necesites el estado de un recurso, no puedas recibir solicitudes entrantes o no haya un evento público para el cambio.
Usa polling para comprobar si un operador aprobó tu número gratuito para enviar mensajes de texto. Bird no tiene un evento de webhook público para esa decisión de verificación. Lee la verificación según un calendario a través de bird sms tfn verifications get, o la herramienta de agente correspondiente. La operación de comando está fuera del bundle público de API.
El polling también funciona en una red que permite solicitudes salientes pero no puede exponer un receptor. Si solo necesitas el estado actual, leer el recurso evita reconstruirlo a partir de eventos pasados.
Las lecturas y listados consumen presupuestos de limitación de solicitudes por credencial activa dentro de una organización. Espera antes de volver a solicitar tras una respuesta HTTP 429. Ajusta el intervalo a la rapidez con que tu aplicación necesita detectar un cambio.
Webhooks, Realtime y límites de solicitudes cubren la configuración de estas vías.
¿Cuál debo elegir?
Elige según quién consume la actualización y qué debe sobrevivir a una desconexión.
- Webhooks cuando tu servidor deba procesar eventos con reintentos y recuperación de eventos perdidos.
- Realtime cuando las pantallas conectadas necesiten actualizaciones y puedan recuperarse desde estado almacenado tras reconectarse.
- Polling cuando necesites el estado de un recurso, no puedas exponer un receptor o no haya un evento público.
- El stream SSE para una sesión de dashboard autenticada de Bird.
En resumen
Elige webhooks para gestionar eventos en el servidor.
Usa reintentos y reproducción de eventos perdidos cuando tu servidor necesite recuperar entregas tras una interrupción.
Elige Realtime para pantallas conectadas.
Restaura la vista desde el estado almacenado cuando el cliente se reconecta.
Elige polling para el estado de un recurso.
Usa polling cuando no puedas exponer un receptor, no haya un evento público o solo necesites el estado del recurso.
Usa SSE para una sesión de dashboard de Bird.
El stream requiere autenticación de sesión de dashboard.