Saltar al contenido principal
Streaming Hub entrega eventos de dos maneras. Los sinks de push (webhook, sqs, rabbitmq, eventbridge) envían cada evento coincidente a un destino que tú posees. Un sink de pull mantiene los eventos en un cursor del lado del servidor que tu consumidor lee en su propio horario. Esta página cubre qué debe hacer tu consumidor en cada caso.

Verificación de una firma de webhook

Streaming Hub firma cada entrega de webhook con un HMAC sobre la marca de tiempo de la solicitud y el cuerpo exacto de la solicitud. La firma prueba que la solicitud vino de Streaming Hub y que no fue alterada ni reenviada. Dos headers llevan la firma: La fórmula de la firma es:
Para verificar una entrega:
  1. Lee el cuerpo sin procesar y la marca de tiempo: verifica antes de parsear el cuerpo, sobre los bytes exactos que recibiste. Cualquier reserialización cambia los bytes y rompe la firma.
  2. Comprueba la frescura: rechaza la solicitud si X-Webhook-Timestamp está a más de 5 minutos de ahora. Esta es la ventana de protección contra replay.
  3. Recalcula la firma: construye signature_input como arriba con tu secreto de firma y codifica en hexadecimal el HMAC-SHA256.
  4. Compara en tiempo constante: compara tu v1,sha256=<hex> con el X-Webhook-Signature recibido mediante una comparación de tiempo constante, segura frente a ataques de tiempo. Rechaza si no coinciden.
  5. Responde: devuelve 2xx solo después de que la firma y la frescura pasen las dos.
Recibes el secreto de firma cuando creas la suscripción, o en tu rotación más reciente. Streaming Hub nunca envía el secreto en un header. El header lleva solo la firma derivada. Consulta crear una suscripción de webhook para saber de dónde viene el secreto.

Manejo de dos firmas durante la rotación

Cuando rotas un secreto de firma, el hub ejecuta un solapamiento de doble firma de 24 horas. Durante el solapamiento cada entrega lleva dos headers X-Webhook-Signature, uno firmado con el secreto nuevo y otro con el secreto anterior. El hub los envía como headers repetidos, así que puedes migrar al secreto nuevo sin perder ninguna entrega. Verifica contra los dos: recalcula la firma esperada con cada secreto que tengas en ese momento y acepta la solicitud si alguna de las firmas recibidas coincide. Una vez que hayas desplegado y confirmado el secreto nuevo, retira el viejo.
Lee X-Webhook-Signature como una lista de valores de header repetidos con el accesor de headers de varios valores de tu framework (o con su vista de headers sin procesar). No dividas una sola cadena unida por comas: el valor de la firma contiene una coma (v1,sha256=…), así que una división ingenua por comas lo corrompe. Algunas pilas HTTP unen los headers repetidos con ", " de forma predeterminada. Usa el accesor de lista para obtener cada valor intacto.

Headers de correlación

Cada entrega de webhook también lleva un conjunto de headers de contexto X-Lerian-*. Un hub single-tenant no envía identidad de tenant en ninguna entrega, incluidas las entregas en cola:
La entrega por webhook no lleva ningún header con la fuente productora. X-Lerian-Event-Type no lleva la fuente a propósito, así que un consumidor no puede distinguir dos productores que emiten la misma clave, a menos que la suscripción fije origin. Crea una suscripción con el origin fijado por cada productor cuando la identidad de la fuente importa.

Deduplicación de entregas

La entrega es al menos una vez: el hub puede entregar el mismo evento más de una vez, mediante reintentos o una reentrega después de que un worker se reinicia. Deduplica por X-Lerian-Event-Id. Es estable en cada reentrega del mismo evento, mientras que X-Lerian-Delivery-Id difiere por intento. Trata un X-Lerian-Event-Id que ya procesaste como un duplicado: confírmalo con un 2xx y no lo vuelvas a procesar. Mantén tu handler idempotente.

Respuesta rápida

Devuelve un 2xx en cuanto hayas verificado y aceptado de forma duradera el evento. Luego haz el trabajo real de forma asíncrona. El hub trata una respuesta con falla, o más lenta que el timeout de intento de la suscripción (10 segundos de forma predeterminada), como una entrega fallida. Una entrega fallida dispara la curva de reintentos. Una respuesta 429 hace que el hub retenga la suscripción completa durante el valor de Retry-After que envías, o durante 30 segundos cuando no envías ninguno, y nunca durante más de 1 hora. Si el destino sigue roto el tiempo suficiente, el hub al final desactiva automáticamente la suscripción.

Lectura de eventos con pull

Una suscripción pull no recibe push. En su lugar, tu consumidor lee una página de sus eventos con:
Los eventos vuelven en orden ascendente de llegada, cada uno con su seq, su ceId (para deduplicar), su tipo y su payload. La respuesta incluye un next_cursor. La lectura es la confirmación (el cursor como confirmación). Traer una página avanza el cursor duradero de la suscripción hasta el seq más reciente que examinó la lectura: el último evento de una página llena y, en una página corta o vacía, el seq más reciente del tenant. No hay una llamada de confirmación aparte. Leer una página la confirma. Esto es monótono, así que nunca retrocede. Para paginar de forma normal, retoma desde el next_cursor del servidor y detente cuando una página corta (con menos elementos que tu limit) devuelve null. Tres comportamientos para tener presentes:
  • Un salto hacia adelante con ?after= puede renunciar al hueco. Cuando pasas ?after=N mayor que tu cursor actual y la lectura devuelve eventos, el cursor avanza más allá de todo hasta N. Una lectura posterior sin ?after= no devuelve los eventos saltados. Esto solo puede pasar con un salto hacia adelante hecho a mano, nunca con la paginación normal por next_cursor.
  • Una suscripción en pausa lee páginas vacías. Cada una de esas lecturas, y la reanudación, mueve el cursor al evento más reciente, así que se omiten los eventos que no habías leído antes de la pausa y los que llegaron durante ella. ?after= todavía los lee dentro de la retención.
  • Un salto hacia atrás con ?after= nunca rebobina. Un ?after= viejo o más bajo que lee una página anterior no mueve el cursor hacia atrás, porque el cursor solo avanza.
Toda respuesta lleva retention_loss. Es null cuando la retención no eliminó nada que esta suscripción aún no hubiera leído. En caso contrario, lleva from_seq y to_seq, el seq más bajo y el más alto que la retención eliminó sin lectura, y detected_at, el momento de la eliminación. Toda lectura que empieza por debajo de to_seq lo reporta. Una página corta mueve el cursor al seq más reciente del tenant, normalmente igual o superior a to_seq, así que la siguiente lectura desde el cursor muestra null. Después de una página llena que termina por debajo de to_seq, o cuando llevas tu propio ?after=, el reporte se repite hasta que una lectura empieza en to_seq o por encima. La lectura con pull tiene rate limit por tenant. Una lectura denegada devuelve 429 con el código rate_limited: espera los segundos de Retry-After y reintenta. Un 503 significa que el hub no puede atender la lectura ahora, y su code nombra la causa (consulta la lista de errores). Espera los segundos de Retry-After y reintenta. Deduplica los eventos leídos con pull por ceId, igual que un consumidor de webhook deduplica por X-Lerian-Event-Id.

Próximos pasos

Gestión de suscripciones

Crea suscripciones, rota secretos y recupera destinos desactivados.

Operación de Streaming Hub

Lee los endpoints de salud del hub.