Ya creaste un trabajo de aprovisionamiento y recibiste un 202: un ID de motor y status: "in_progress". Ahora el agente de IA está recorriendo tus fuentes y aplicando voces de marca, elementos del glosario e instrucciones a ese motor en segundo plano. Esto puede tardar un poco o bastante, según cuántos enlaces tenga que rastrear. Podrías dejar abierto un WebSocket en vivo para ver cómo avanza, pero preferirías no mantener una conexión abierta solo para enterarte de cuándo terminó el agente y qué fue lo que creó.
Para eso está el webhook. Cuando pasas un callbackUrl al crear el trabajo, Lingo envía por POST el resultado final a esa URL en cuanto el trabajo termina: te avisa cuando el motor está listo, junto con el inventario de lo que se creó. Si el trabajo termina correctamente, llega como provisioning.completed con el resumen de cada registro que creó la IA. Si falla, llega como provisioning.failed con la razón. En ambos casos, tu flujo de configuración se entera sin tener que preguntar.
Esta página cubre los dos payloads y cómo manejarlos. La entrega va firmada y se reintenta; esa mecánica se comparte con localización y se documenta en la página de verificación de firma de webhook, enlazada justo donde la vas a necesitar.
En esta página
- Cómo funciona la entrega
- El payload completed
- El payload failed
- Cómo manejar un webhook
- Cuándo la entrega no es la herramienta adecuada
Cómo funciona la entrega#
Un trabajo de aprovisionamiento termina una sola vez. En el instante en que llega a un estado terminal —ya sea porque todas las fuentes se rastrearon y analizaron, o porque la ejecución se abandonó—, su resultado se entrega a tu callbackUrl como un único POST. Un grupo de localización se divide en un trabajo por cada idioma de destino, y cada uno entrega su propio callback; un trabajo de aprovisionamiento es un solo trabajo, así que hay una sola entrega.
Define el destino con callbackUrl cuando crees el trabajo. Por la red viajan dos formatos de payload, diferenciados por su campo type: provisioning.completed y provisioning.failed. Ambos indican el jobId y el engineId al que pertenecen, así que un solo handler puede enrutar según type y actualizar el registro correcto.
Solo HTTPS
callbackUrl debe usar HTTPS. Si intentas crear el trabajo con una URL HTTP, se rechaza: el webhook va firmado, y enviar un payload firmado sobre texto plano le quita todo el sentido.
Maneja con elegancia los tipos de evento desconocidos
Hoy por hoy, por la red viajan provisioning.completed y provisioning.failed. Trata ese conjunto como abierto: bifurca según los tipos que conoces e ignora el resto, para que un tipo de evento futuro no rompa un handler ya desplegado.
El payload completed#
Cuando el trabajo termina, el payload incluye el summary: el mismo inventario que obtendrías al consultar el trabajo, pero enviado hacia ti en lugar de tener que sondearlo. Enumera cada voz de marca, elemento del glosario e instrucción que la IA creó en tu motor, y también cualquier fallo por elemento que haya encontrado en el proceso.
{
"type": "provisioning.completed",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"summary": {
"brandVoices": { "count": 3, "ids": ["bv_A1b2C3d4", "bv_B2c3D4e5", "bv_C3d4E5f6"] },
"glossaryItems": { "count": 12, "ids": ["gi_A1b2C3d4", "..."] },
"instructions": { "count": 5, "ids": ["ins_A1b2C3d4", "..."] },
"errors": []
}
}| Campo | Descripción |
|---|---|
type | provisioning.completed |
jobId | El trabajo de aprovisionamiento que terminó (prefijo pjb_) |
engineId | El motor que configuró (prefijo eng_) |
summary | Lo que la IA creó en el motor: conteos e IDs por componente, además de fallos por elemento en errors |
El summary es el mismo objeto que incluye el trabajo, y su significado campo por campo —qué representa cada componente, cómo se asignan los elementos a los idiomas y qué cae en errors— está documentado una sola vez en Qué extrae la IA. Aquí basta con saber que el payload completed te entrega los IDs de todo lo que construyó el agente, para que tu handler pueda registrarlos o mostrarlos en tu panel sin volver a consultar el trabajo.
Un arreglo errors no vacío igual llega como completed
Los fallos por elemento no hacen fallar el trabajo completo. Si una sola fuente no se pudo rastrear o un registro no se pudo crear, eso cae en summary.errors y el resto igual se aplica al motor; el payload sigue siendo provisioning.completed, no provisioning.failed. El evento completed significa que el trabajo llegó hasta el final; revisa errors para ver qué hay que corregir. Solo se envía un payload provisioning.failed cuando la ejecución no produjo ningún motor utilizable.
El payload failed#
Un trabajo de aprovisionamiento falla cuando la ejecución no produce nada con lo que se pueda trabajar; por ejemplo, si ninguna fuente se puede rastrear, el agente no tiene contenido para analizar. Cuando eso pasa, igual se te avisa. El tipo de payload es provisioning.failed y lleva una cadena error en lugar del resumen:
{
"type": "provisioning.failed",
"jobId": "pjb_A1b2C3d4E5f6G7h8",
"engineId": "eng_X1y2Z3a4B5c6D7e8",
"error": "All sources failed to crawl. No content available for analysis."
}| Campo | Descripción |
|---|---|
type | provisioning.failed |
jobId | El trabajo de aprovisionamiento que falló |
engineId | El motor que se creó pero quedó sin configurar |
error | Razón legible para humanos por la que el trabajo no pudo completarse |
Aquí está la parte que un lector escéptico haría bien en preguntar: si el trabajo falló, ¿también perdí el motor? No. El engineId de este payload es el mismo motor que recibiste en el 202: sigue existiendo, se creó en el momento en que hiciste la llamada, solo que sin la configuración que habría agregado la ejecución fallida. Un fallo te cuesta la extracción, nunca el motor. Ajusta lo que enviaste y vuelve a intentarlo, o configura el motor manualmente desde el panel. Cuando un trabajo falla durante el rastreo, normalmente el problema son las fuentes: Tipos de fuente explica qué hace que una fuente valga la pena.
Cómo manejar un webhook#
La primera duda de un lector escéptico aquí es la correcta: mi handler hace trabajo real —escribe en la base de datos, envía una notificación, actualiza el panel—, así que ¿no va a dejar la conexión abierta el tiempo suficiente como para que el webhook agote el tiempo de espera?
Sí, así que no hagas esperar a Lingo. Devuelve 200 primero y procesa después. Acusa recibo y deja el trabajo real para después de enviar la respuesta. El contrato completo de entrega —por qué conviene confirmar primero y cuál es el calendario de reintentos si no lo haces— está en la página de firma y entrega; el handler de abajo muestra la forma que toma para un payload de aprovisionamiento.
app.post("/webhooks/provisioning", verifyWebhook, async (req, res) => {
// Acknowledge first - the job ends once, so this fires once.
res.status(200).send("ok");
const { type, jobId, engineId } = req.body;
if (type === "provisioning.completed") {
const { summary } = req.body;
await db.engines.update({
where: { engineId },
data: {
status: "ready",
brandVoiceCount: summary.brandVoices.count,
glossaryCount: summary.glossaryItems.count,
instructionCount: summary.instructions.count,
},
});
}
if (type === "provisioning.failed") {
console.error(`Provisioning failed: ${jobId} (${engineId})`, req.body.error);
await db.engines.update({
where: { engineId },
data: { status: "needs_configuration" },
});
}
});El middleware verifyWebhook es la única pieza que esta página no define. Cada entrega va firmada según la especificación Standard Webhooks: tres headers, un HMAC sobre el cuerpo sin procesar y un secreto whsec_ generado la primera vez que envías un trabajo con callback. Los callbacks de aprovisionamiento y localización usan exactamente ese mismo esquema, así que se documenta una sola vez en verificación de firma de webhook. Conecta el middleware antes de confiar en cualquier payload: un cuerpo no verificado es un cuerpo no autenticado.
Verifica antes de confiar en el cuerpo
Tu endpoint es una URL pública; cualquiera puede hacerle POST. Verifica la firma contra el cuerpo sin procesar de la solicitud antes de actuar sobre cualquier payload: antes de marcar un motor como listo o de guardar los IDs que dice haber creado. El cómo —los headers, el HMAC y el secreto whsec_— está en la página de verificación de firma.
Cuándo la entrega no es la herramienta adecuada#
El webhook es una comodidad de envío, no el sistema de registro. Hay dos casos en los que conviene usar otra cosa, y ambos están a un clic de distancia.
Si tu endpoint estaba caído cuando se entregó el resultado, la plataforma reintenta con el mismo calendario que usa cualquier webhook de Lingo, y el resultado no queda atrapado en el callback. Los registros que creó la IA son la configuración real del motor; el resumen completed es un informe de trabajo que ya ocurrió sobre un motor real, no la única copia de esa información. Así que un periodo de inactividad te cuesta una notificación, nunca el motor. El calendario de reintentos en sí está en la página de firma y entrega.
Y si lo que quieres es progreso en vivo mientras se configura el motor —un estado de rastreo y luego configuración en una UI, en lugar de un único callback a tu servidor cuando termina—, entonces lo que buscas es el WebSocket del trabajo de aprovisionamiento, no el webhook. Transmite un snapshot al conectarte y eventos de progreso a medida que avanza la ejecución, y puedes conectarte en cualquier momento, incluso después de que el trabajo haya terminado.
